Skip to main content

Full text of "ibm :: apl :: GC26-3847-0 APL Language Mar75"

See other formats


GC26-3847-0 
File No. S370-22 



Systems 



APL Language 



FT 5 } 




PREFACE 



This manual is intended to provide a reference for the APL language, 
and also an introduction to APL to those unfamiliar with it. New users 
should read the introduction, which provides an overview of some 
fundamental concepts, and illustrates several kinds of use. 

Section 2 presents the fundamentals and introduces the terminology 
used in later sections, but the sections may otherwise be read 
relcitively independently. For example, a glance at the listing of the 
primitive functions in Figures 3.1 and 3.5 should suffice for the reader 
who wishes to concentrate just on the means of defining and using 
functions (programs) presented in Sections 6 and 7. 

Readers familiar with earlier versions of APL but not with the 
notions of shared variables, will find this topic and the related topics 
of system functions and system variables covered in Sections 4 and 5. 

The following publications are intended to supplement the information 
in this publication for particular APL systems: 

APL Shared Variables (APLSV) User's Guide, Order No. SH20-1460 
APL/CMS User's Guide, Order No. SC20-1846 



First Edition (March 1975) 

This publication serves two different APL systems: APL Shared 
Variables (Program Number 5799-AJF — Programming RPQ WE1191) and 
APL/CMS (Program Number 5799-ALK — Programming RPQ MF2608) . 

Changes may from time to time be made to the specifications herein; any 
such changes will be reported in subsequent revisions or Technical 
Newsletters. Before using this publication, consult the latest IBM 
System/360 and System/370 Bibliography , Order No. GA22-6822, for the 
editions that are applicable and current. 

Reqxiests for copies of IBM publications should be made to your IBM 
representative, or to the IBM branch office serving your locality. 

A form for readers ' comments is provided at the back of this 
publication. If the form has been removed, comments may be addressed to 

IBM Corporation 

Systems Development Division 

LDF Publishing — Department JO 4 

1501 California Avenue 

Palo Alto, CA 94304. 

©Copyright International Business Machines Corporation 1975 



CONTENTS 

SECTION 1 : INTRODUCTION ..... 1 

Two Examples of the Use of APL 1 

An Isolated Calculation 1 

A Prepared Workspace 2 

The Characteristics of APL 7 

SECTION 2: FUNDAMENTALS 9 

Character Set 10 

Scalar and Vector Constants ... 10 

Spaces 13 

Functions 13 

Order of Execution 14 

Arrays 14 

Workspaces and Libraries 15 

Names 16 

User Identification 16 

SECTION 3: PRIMITIVE FUNCTIONS AND OPERATORS 17 

Scalar Functions 17 

Plus, Minus, Times, Divide and Residue 19 

Conjugate, Negative, Signum, Reciprocal and Magnitude 20 

Boolean and Relational Functions 20 

Minimum and Maximum 21 

Floor and Ceiling 21 

Roll (Random Number Function) 22 

Power, Exponential, General and Natural Logarithm 22 

Circular, Hyperbolic, and Pythagorean Functions 23 

Factorial and Binomial Functions 24 

Operators 25 

Reduction 25 

Scan 26 

Axis 27 

Inner Product 27 

Outer Product '. 29 

Mixed Functions 29 

Structural Functions 31 

Shape, Reshape, and Ravel 31 

Reverse and Rotate 33 

Catenate and Laminate 33 

Transpose 35 

Selection Functions 36 

Take and Drop 36 

Compress and Expand 36 

Indexing 37 

Selector Generators 38 

Index Generator and Index of 38 

Membership 39 

Grade Functions 39 

Deal 39 

Numerical Functions . 40 

Matrix Inverse and Matrix Divide 40 

Decode and Encode 42 

Data Transformations 43 

Execute and Format 43 

SECTION 4: SYSTEM FUNCTIONS AND SYSTEM VARIABLES 47 

System Functions 47 

Canonical Representation 47 

Function Establishment .... 47 

Expunge 48 

Name List 49 

Name Classification 49 

Delay 49 

System Variables 50 

Contents iii 



SECTION 5: SHARED VARIABLES 52 

Offers „ 52 

Access Control . 55 

Retraction 58 

Inquiries 58 

SECTION 6: FRICTION DEFINITION 59 

Canonical Representation and Function Establishment ....... 59 

The Function Header 60 

Local and. Global Names 61 

Branchincr and Statement Numbers 61 

Labels 62 

Comments 62 

Function Ed.itina - the V Form 6 3 

Addincr a Statement 63 

Inserting or Replacina a Statement 6 3 

Replacing the Header 63 

Deleting a Statement 6 3 

Editing a Statement or Header 6 4 

Addina to a Statement or Header 6 4 

Function Display 6 4 

Leaving the V Form 65 

SECTION 7: FRICTION EXECUTION 66 

Halted Execution 66 

State Indicator ......... 67 

State Indicator Damage 68 

Trace Control . 68 

Stop Control 68 

Locked Functions 69 

Recursive Functions 69 

Terminal Input and Output 70 

Evaluated Input 71 

Interrupting Evaluated Input ... 71 

Character Input 71 

Interrupting Character Input .... 71 

Normal Output 72 

Bare Output . 72 

SECTION 8: SYSTEM COMMANDS .... 73 

Commands that Modify the Workspace Environment .... 76 

Grouping to Facilitate Copyina or Erasure .... 78 

Commands that Monitor the Active Workspace .... 79 

Commands for Workspace Storage and Retrieval ... 80 

Libraries of Saved Workspaces .... 80 

Names and Passwords for Workspaces 80 

Automatic Savina after Line Drop 

•and Special Properties of the C OUT I HUE Workspace ....... 83 

Commands Recrarding Workspace Storage and Retrieval ........ 83 

Access to the System 83 

Sign On 84 

Sign Off 84 

INDEX 87 



iv APL Language 



ILLUSTRATIONS 



Figure 



Title 



Paae 



Figure 


1. 


,1 


Figure 


2. 


,1 


Figure 


2. 


.2 


Figure 


2, 


.3 


Figure 


3, 


.1 


Figure 


3. 


,2 


Fiaure 


3. 


,3 


Figure 


3. 


,4 


Figure 


3. 


,5 


Figure 


3. 


,6 


Figure 


3. 


,7 


Figure 


4, 


.1 


Figure 


4. 


,2 


Figure 


5, 


.1 


Figure 


5, 


.2 


Figure 


5, 


,3 


Figure 


8, 


.1 


Figure 


8, 


,2 


Figure 


8. 


.3 



Functions for Sales, Billina, and Inventory Control ... 6 

Error Reports 11 

The APL Character Set 12 

Typical APL Keyboard ......... 12 

Primitive Scalar Functions 18 

Identity Elements of Primitive Scalar Dyadic Functions . 19 

The Pythagorean Functions 2 4 

Inner Product 28 

Primitive fixed Functions 30 

Scalar-Vector Substitutions for fixed Functions .... 31 

Shape and Rank Vectors 32 

System Functions 48 

System Variables 51 

Functions for the Management of Sharing 5 3 

Access Control of a Shared Variable 56 

Some Useful Settings for the Access Control Vector ... 57 

System Commands 7 4 

Trouble Reports 75 

Environment Within a Clear Workspace 76 



Illustrations 



SECTION 1 ; INTRODUCTION 

APL is a general-purpose language which enjoys extensive use in 
such diverse applications as commercial data processing, system design, 
mathematical and scientific computation, and the teaching of mathematics 
and other subjects. It has proved particularly useful in data-base 
applications, where its computational power and communication facilities 
combine to enhance the productivity of both application programmers and 
end users. 

When implemented as a computing system, APL is used from a 
typewriter-like keyboard. Statements that specify the work to be done 
are entered by typing them, and in response the computer displays the 
result of the computation. The result appears at a device which 
accompanies the keyboard, such as a printer, or video display. In 
addition to work purely at the keyboard and its associated display, 
entries may also invoke the use of printers, disk-files, tapes or other 
remote devices . 

TWO EXAMPLES OF THE USE OF APL 

A statement entered at the keyboard may contain numbers , or 
symbols such as + - x *, or names formed from letters of the alphabet. 
The numbers and special symbols stand for the primitive objects and 
functions of APL; primitive in the sense that their meanings are 
permanently fixed, and therefore understood by the APL system without 
further definition. A name, however, has no significance until a 
meaning has been assigned to it. 

Names are used for two major categories of objects. There are 
names for collections of data, made up of numbers or characters. Such a 
named collection is. called a variable . Names may also be used for 
programs made up of sequences of APL statements. Such programs are 
called defined functions . Once they have been established, names of 
variables and defined functions can be used in statements by themselves 
or in combination with the primitive functions and objects. 

AN ISOLATED CALCULATION 

If the work to be done can be adequately specified simply by 
keying a statement made up of numbers and symbols, names will not be 
required: entering the expression to be evaluated causes the result to 
be displayed. For example, suppose it is required to compare the rates 
of return on money at a fixed interest rate but with different 
compounding intervals. For 1000 units at 6%, compounded annually, 
quarterly, monthly, or daily, for 10 years, the transaction (at a 
typewriter terminal) would look like this: 

1000x(l+. 06*1 4 12 365)*10xl 4 12 365 (entry) 
1790.85 1814.02 1819.4 1822.03 (response) 

(The largest gain is apparently obtained in going from annually to 
quarterly, and after that the differences are relatively insignificant.) 

Several distinctive features of APL are illustrated in this 
example: familiar symbols such as + x * are used where possible; 
symbols are introduced where necessary, (as the * for the power 
function) ; and a group of numbers can be worked on together. 



Section 1 : Introduction 



A PREPARED WORKSPACE 

Although there are many problems that can be solved by keying in 
the appropriate numbers and symbols, the greatest benefits of using APL 
come when named functions and data are used. Since a single name may 
refer to a large array of data, using the name is far simpler than 
keying in all of its members. Similarly, a defined function, invoked by 
entering its name , may be composed of many individual APL statements 
that, would be burdensome to type individually again and again. 

Once a function has been defined, or data collected under a name, 
it is usually desirable to retain the significance of the names for 
some period of time; perhaps for just a few minutes, but more often for 
much longer periods, possibly months or years. For this reason APL 
systems are organized around the concept of a workspace , which might be 
thought of as a notebook in which all the different items needed during 
some piece of work are recorded together. 

The following example illustrates the use of an application 
package - a workspace prepared for a particular data-processing 
application. It is not expected that the reader new to APL will 
immediately follow all details, but the example should nevertheless 
provide, on the one hand, an indication of the ease of exploring and 
using such a package, and on the other hand, the relative ease of 
constructing it. 

The example is a skeletal system for sales, billing, and inventory 
control for, say, a wholesale distributor of gadgets. The system 
maintains an inventory of items in stock, with part numbers, 
descriptions, unit prices, quantities on hand, and reorder levels. It 
automatically adjusts the quantity on hand when an invoice is prepared, 
and signals when the stock level goes below the reorder level. It also 
provides for entering new stock items in the inventory list and has 
provision for order entry and printing of invoices. 

To complete this basic system for actual application, it would be 
necessary to add functions such as the recording of a journal and the 
maintenance of the customer list, and to add appropriate checks on 
errors of input and on security. Nevertheless, the package does work, 
as far as it goes, and in addition to showing the use of many functions 
of the language, also demonstrates the conciseness of APL programming. 

To start, the stored workspace containing the application package 
is activated, using a system command : 

)LOAD 1 SBIC 
SAVED 18.42.25 02/06/75 

To become acquainted with the contents of the package the names of 
variables and defined functions are listed: 

)VARS 
CUSTLIST DESCRIBE INVNO LOW MTH ORDLIST 

STOCKLIST 

)FNS 
ADDRESS DATE GET INVOICE NEWSTOCK ORDER ORDERENTRI 

PRINT PUT RESTOCK 



APL Language 



The variable name DESCRIBE is suggestive. Its value can be 
displayed by simply entering the name: 

DESCRIBE 
THIS WORKSPACE CONTAINS FUNCTIONS FOR RECORDING ORDERS, 
MAINTAINING AN INVENTORY, AND PREPARING INVOICES. IT IS A 
SKELETAL SYSTEM DESIGNED TO ILLUSTRATE THE USE OF APL IN 
COMMERCIAL DATA PROCESSING. 

THE VARIABLES CUSTLIST , ORDLIST , AND STOCKLIST CARRY, 
RESPECTIVELY , CUSTOMER NAMES AND ADDRESSES KEYED TO A 
CUSTOMER NUMBER, ORDERS BY STOCK NUMBER AND CUSTOMER NUMBER, 
AND THE INVENTORY LIST OF STOCK ITEMS. INVNO IS A COUNTER 
FOR SUCCESSIVE INVOICE NUMBERS, LOW INDICATES ITEMS TO BE 
REORDERED, AND MTH HOLDS NAMES FOR MONTHS OF THE YEAR. 

WHEN DISPLAYING THE STOCK LIST OR CUSTOMER LIST ON A 
TYPEWRITER TERMINAL IT WILL BE DESIRABLE TO CHANGE TO A 
TYPE-ELEMENT HAVING BOTH UPPER AND LOWER CASE ALPHABETS. 

MEANINGFUL STATEMENTS IN THIS WORKSPACE ARE: 

NEWSTOCK 

ORDERENTRY 

PRINT INVOICE ORDER N 

RESTOCK 

WHERE N IS A CUSTOMER NUMBER. FOR CONSISTENCY WITH THE DATA 
ALREADY ENTERED, NEWSTOCK AND PRINT SHOULD ALSO BE USED 
WITH A TYPE-ELEMENT THAT HAS BOTH ALPHABETS. 

THE FUNCTIONS ADDRESS, DATE, GET, AND PUT ARE NOT 
NORMALLY INVOKED BY A DIRECT KEYBOARD ENTRY, BUT ARE USED BY 
THE VARIOUS FUNCTIONS NOTED ABOVE. 

It might be helpful at this point to display STOCKLIST to see just 
what the information looks like. But the list might be very large, and 
it is good practice to find out its size before asking for the display: 

pSTOCKLIST 
6 39 

The list has 6 rows and 39 columns, which is not too much to 
display in its entirety. Following the advice in DESCRIBE the 
type-element can be changed and the variable name entered: 

stocklist 
1135 First Great Item 
9993 High Flyer Widget 
3569 Second Moneymaker 
5613 Mail Order Special 
2583 A Real Winner 
9998 Nonesuch Frammis 

Next it might be useful to look at the customer list: 

pCUSTLIST 
3 5 20 



9.95 


350 


55 


88.73 


240 


35 


24.75 


200 


30 


14.99 


600 


95 


49.99 


125 


10 


2.69 


500 


50 



Section 1 : Introduction 



The customer list is apparently represented by a three-dimensional 
array, and it will be interesting to see how it is displayed: 

custlist 
7 
City Traders Inc. 
41 Postage Road 
Rimela, N. Y. 12345 

55 
Mail House Ltd. 
7-11 Ramblers Lane 
Offshore island 
City, S. Dak. 54321 

312 

Mantup Sales Corp. 

Ruralia Farms 

RFD 2 

Suburbian, Wis. 0000 

Finally, it is probably worth looking at the order list: 

pORDLIST 
6 3 

ORDLIST 

55 3569 5 

312 9998 12 

7 1135 2 

312 3569 10 

312 5613 45 

7 5613 75 

This is a 3-column numerical array, and the significance of 
each column is easily deduced from the previous displays: the sucessive 
columns appear to represent customer number, stock number, and quantity. 

Use of the package can be demonstrated by trying the meaningful 
statements : 

ORDERENTRY 
CUSTOMER ITEM QUANTITY 

In response to the statement ORDERENTRY the system has displayed column 
headings, and the keyboard has unlocked for further entry. These can be 
supplied, using some of the existing customer and item numbers. The 
entire transaction at the terminal might be this : 

ORDERENTRY 
CUSTOMER ITEM QUANTITY 
55 1135 12 
312 1135 24 
55 2583 4 

Since customer 5 5 had one item on order before, three should be on order 
now. 



APL Language 



Although it is not listed as a meaningful statement, what happens 
if the function ORDER is used by itself? 



ORDER 5 5 
55 3569 5 
55 1135 12 
55 2583 4 

This entrv produces a result which seems to confirm the number of items 
on "rderf It turns out that this result will be used by INVOICE to 
produce a result which will in turn be used by PRINT. 

invoice order 55 
1336 
3569 Second Moneymaker 
1 1 35 First Great Item 
2583 A Real Winner 

If the complete statement given in DESCRIBE is entered rather then 
these piecemeal entries, the result is a formatted output xntended to be 
used with a pre-printed form: 

print invoice order 55 







55 


24.75 


5 


123.75 


9.95 


12 


119.40 


49.99 


4 


199.96 



To: 



Mail House Ltd. 
7-11 Ramblers Lane 
Offshore Island 
City, S. Dak. 54321 



Invoice No. 
1336 

Feb 8, 1975 



Stock 



3569 
1135 
2583 



Description 



Second Moneymaker 
First Great Item 
A Real Winner 



Price 



24.75 

9.95 

49.99 



Quan. 



5 
12 

4 



Exten. 



123.75 
119.40 
199.96 



Total $ 443.11 



Distributors Corp. 123 First Ave., City, St. 99999 



For the sake of completeness, and because they illustrate 
variations in the method of requesting input, the remaining two 
statements can be entered. NEWSTOCK prints a prompting message and then 
unlocks the keyboard, waiting for entry of the response on the same 
line: 

newstock 
stock number/ 8760 
description/ The Best Gadget 
unit price/ 1.73 
initial inventory/ 875 
reorder level/ 100 

RESTOCK not only prints a prompting message, but uses an 
additional prompt D: supplied by the system: 

RESTOCK 
STOCK NUMBER 

D: 

1135 
STOCK INCREMENT 

D: 

30 



Section 1 : Introduction 



9 


95 


368 


55 


88 


73 


240 


35 


24 


75 


195 


30 


14 


99 


600 


95 


49 


99 


121 


10 


2. 


69 


500 


50 



It might now be of interest to display the inventory once more to 
see the effect of the previous operations: 

stocklist 
1135 First Great Item 
9993 High Flyer Widget 
3569 Second Moneymaker 
5613 Mail Order Special 
2583 A Real Winner 
999 8 Nonesuch Frammis 
8760 The Best Gadget 1.73 875 100 

The quantities on hand do indeed show the effect of completing the 
order, replenishing the stock, and adding a new item. 

The complete set of ten functions in this package is displayed in 
Figure 1.1. The first line in each definition is the function head er, 
which specifies, among other things, the function name and syntax"! — The 
remainder in each individual display is the function body . The longest 
function, INVOICE, has twelve lines, the shortest, ORDER, has only one. 



FORM-SPRINT N;T;X 

X+l+pN 

F0RM<r~H<b 12 43 +ADDRESS 1 ~6 +W 

F0flM[l;37+i6>6+ff[l; ] 

FORMl3;31+\12]+DATE QTS 

F0RMi5+xX-l;l«- 1 +ff 

F0RML12; ]-<-~43 + T + /i , 1 35 IN 



1]) 



Z+INVOICE N;R;X;PQR;EXT 
X+ 6 VlNVNO+INVNO+1 
Z+ 1 43 p(X, 37 TtfCl; 

PQR+&.251R+GET J[2] 
EXT-rXL3lxPQRH] 

2*Z,[l3(31+i?), 4 8 2 ?Xl3l,EXT 

PQRL21+PQR121-X131 

■+(>/PQRL2 3])/£2 

L0W+L0WA~Xl2leL0W) /XZ21 

£2:fl[31+i4]-e 4 fPQi?[2] 

R PUT ATC 2] 

-»-(0*l + pilM- 1 +ff)/Ll 



Z+ORDER N 

Z«-( ORDLISTl -,U=N) /ORDLIST 



Z+ADDRESS Nil 

J> ( CUSTLISTl ;l;i6]A. = ,tf)il 

Z«- 1 ICUSTLISTH; ;] 



Z+DATE N 

Z+-MTHlNL2l;l, 3 6 «[3 1] 

Z[7>»,» 



NEWSTOCKiR 

EH-' STOCK NUMBER/ • 

R+ 4 Tid 

CD-*-' DESCRIPTION/ ' 

i?-«-fl,21 + 12 + [Il 

ek ' wit price/ ' 

i?+-i?, 6 2 TIB 

PH-'JffJ2\ZVl£ INVENTORY/ 

R+R, 4 t±H 

EH-' REORDER LEVEL/ ' 

fl«-fl, 4 TiE 

i? PUTsl^*R 



ORDERENTRI ; L 

' CUSTOMER ITEM QUANTITY* 

LI :-►( ' 'A. =L-f-[3)/0 <** - 

ORDLIST+ORDLIST,tlli.L 

■+L1 



RESTOCK;R;X;PQR 

< STOCK NUMBER' 

PQR<r±25iR+GET X<-Q 

' STOCK INCREMENT' 

i?[31 + i4]«- 4 VPQRL21+PQR121+Q 

R PUT X 



R PUT Nil 

I+{STOCKLIST\_ ;i4]a.= 4 wN)\l 
+ (.I*l + pSTOCKLIST)/Ll 
STOCKLIST+STOCKLIST. Ill ' ' 
L1-.ST0CKLISTLI; >i? 



Z-<-0£T #;I 

If-(52 , 0CXLJ52'C;i4]A.= 4 Ti7) 1 1 
Z+STOCKLISTHil 



Figure 1.1: Functions for Sales, Billing, and Inventory Control 



APL Language 



The details of the programming will not be discussed here, but one 
point is worth noting. As they stand here the various data lists are 
very small. In a real use, one or more of them might have many 
thousands of entries. A good way to handle them in that case is 
illustrated by the treatment of STOCKLIST, which is accessed only by the 
functions put and GET, rather than the primitive APL functions which 
could have been used directly for this purpose. By thus isolating the 
access functions the application package design is automatically made 
more general; if a different representation were chosen for STOCKLIST - 
say, an external file- the required changes in the programming would be 
confined to the definitions of PUT and GET, and the other functions such 
as INVOICE or NEWSTOCK, which give the package its particular character, 
would be unaffected. In this way, .an APL application can be expanded to 
data-bases of arbitrary size, well beyond the storage capacity of the 
workspace that establishes the environment for the work. 

THE CHARACTERISTICS OF APL 

The subsequent sections of this manual describe APL in detail, 
giving the meaning of each symbol and discussing the various features 
common to the APL systems currently available from IBM. It is well to 
view these, details in light of the major characteristics of APL, which 
may be summarized as follows: 

The primitive objects of the language are arrays (lists, tables, 
lists of tables, etc.). For example, A+B is meaningful for any 
arrays A and B, the size of an array \pA) is a primitive function, 
and arrays may be indexed by arrays, as in yl[3 l 4- 2] 

The syntax is simple: there are only three statement types (name 
assignment, branch, or neither) , there is no function precedence 
hierarchy, functions have either one, two, or no arguments, and 
primitive functions and defined functions (programs) are treated 
alike. 

The semantic rules are few: the definitions of primitive functions 
are independent of the representations of data to which they apply, 
all scalar functions are extended to other arrays in the same way 
(that is, item-by-item) , and primitive functions have no hidden 
effects (so-called side-effects) . 

The sequence control is simple: one statement type embraces all 
types of branches (conditional, unconditional, computed, etc.), and 
the termination of the execution of any function always returns 
control to the point of use. 

External communication is established by means of variables which 
are shared between APL and other systems or subsystems. These 
shared variables are treated both syntactically and semantically 
like other variables. A subclass of shared variables, system 
variables , provides convenient communication between APL programs 
and their environment. 

The utility of the primitive functions is vastly enhanced by 
operators which modify their behavior in a systematic manner. For 
example, reduction (denoted by /) modifies a function to apply over 
all elements of a list, as in +/L for summation of the items of £. 
The remaining operators are scan (running totals, running maxima, 
etc.), the axis operator which, for example, allows reduction and 
scan to be applied over a specified axis (rows or columns) of a 
table, the outer product , which produces tables of values as in 
RATE" ,*YEARS for an interest table, and the inner product , a simple 
generalization of matrix product which is exceedingly useful in data 
processing and other non-mathematical applications. 

Section 1 : Introduction 7 



The number of primitive functions is small enough that each is 
represented by a single easily-read and easily-written symbol, yet 
the set of primitives embraces operations from simple addition to 
grading (sorting) and formatting. The complete set can be 
classified as follows: 

Arithmetic : + -xt*«o|L["!S 
Boolean and Relational : vava~<<; = 2:>* 
Selection and Structural: /\j<\[;] + + p,4>$e 
General: e\?iT^iiv 



8 APL Language 



SECTION 2; FUNDAMENTALS 
A typical statement in APL is of the form: 

AREA-*-?,*** 

The effect of the statement is to assign to the name AREA the value of 
the expression 3x4 to the right of the specification arrow «- ; the 
statement may be read informally as "AREA i£ three times four." 

The statement is the normal unit of execution. Two primitive 
types occur, the specification illustrated above, and the branch , which 
serves to control the sequence in which the statements in a defined 
function (discussed in Section 6) are executed. There is also a third 
type of statement which may invoke the use of a defined function without 
either a specification or a branch. 

A variant of the specification statement produces display of a 
result on the medium (paper or screen) provided by the terminal device; 
if the leftmost part of a statement is not a name followed by a 
specification, the result of the expression is displayed. For example: 



12 



14 



3x4 

PERIMETER*-2x(3 + H) 
PERIMETER 



Printing of the result of any part of a statement can be obtained 
by including the characters Q+ at the appropriate point in the 
statement. Moreover, any number of specification arrows may occur in a 
statement. For example: 



12 
14 
4 



Xf-2+D-*-3xY-<-4 

X 

Y 



The terminal entry and display devices used with APL systems 
include a variety of typewriter-like and display-tube devices. Their 
characteristics vary, but the essential common characteristics are: 

1. The ability to enter and display APL characters. 

2. A means of signalling completion (and release to the system) of an 
entry. 

3. Facilities for convenient revision of an entry before release. 

4. Facilities to interrupt execution at the end of a statement ( weak 
interrupt ) and within a statement ( strong interrupt ) . 

5. A cursor , such as an arrowhead, to show where on the line the next 
character entered will appear. 

All examples in this manual are presented as produced on a 
typewriter-like device on which the release signal is produced by the 
carrier return key, and revision is handled by backspacing to the point 
of revision, striking the attention button, and entering the revision. 
A caret supplied by the system marks the point of correction. For 



Section 2 : Fundamentals 



example : 



18 



3+4x5+ 

A 

+ 5 + 6 



On terminals of this type the attention key is also used for 
interrupting execution. A single strike of this key while execution is 
in progress provides a weak interrupt, and a double strike provides a 
strong interrupt. 

Entry of a statement which cannot be executed will invoke an error 

re P ort . which indicates the nature of the error and the point at which 

execution stopped. For example: 

Z-f-5 

3+(YxX ) 
VALUE ERROR 

3+(7xZ) 

A 

Error messages are listed in Figure 2.1, together with information on 
the cause and suggested corrective action. 

CHARACTER SET 

The characters which may occur in a statement fall in four main 
classes: alphabetic, numeric, special, and blank. The alphabetics 
comprise the roman alphabet in upper case italic font, and the same 
alphabet underscored. The entire set is shown in Figure 2.2 together 
with suggested names and the scheme for forming (as composites of other 
symbols) those which may not be directly available on the keys of 
certain terminal devices. A typical keyboard layout is shown in Figure 

The names suggested are for the symbols themselves and not 
necessarily for the functions they represent. For example, the 
downstile L represents both the minimum , a function of two arguments, 
and the floor (or integer part ) , a function of one argument. In 
general, most of the special characters (such as +, -, x, and *) are 
used to denote primitive functions which are assigned fixed meanings, 
and the alphabetic characters are used to form names which may be 
assigned and re-assigned significance as variables, defined functions, 
and other objects. The blank serves as a separator to mark divisions 
between names (which are of arbitrary length) . 

For terminal devices which permit the display font to be changed 
without changing the behavior of the entry keyboard or communication 
with the system (as in changing the typing element on certain 
typewriters), any available display font may be used. For example, in 
textual work a font with normal upper- and lower-case roman is commonly 
employed. 

SCALAR AND VECTOR CONSTANTS 

All numbers entered or displayed are in decimal, either in 
conventional form (including a decimal point if appropriate) or in 
scaled form. The scaled form consists of an integer or decimal fraction 
callesd the multiplier followed immediately by the symbol E followed 
immediately by an integer (which must not include a decimal point) 
called the scale . The scale specifies the power of ten by which the 
multiplier is to be multiplied. Thus l . 44E2 is equivalent to 144. 

1 APL Language 



TYPE 



CHARACTER 

DOMAIN 
DEFN 



Q— IMPLICIT 



INDEX 

INTERFACE 

QUOTA 

EXHAUSTED 

INTERRUPT 



LENGTH 
NO SHARES 
RANK 
RESEND 

SI DAMAGE 
SYNTAX 



SYMBOL 

TABLE 

FULL 

SYSTEM 



VALUE 



WS FULL 



Cause; CORRECTIVE ACTION 



Illegitimate overstrike. 

Arguments not in the domain of the function. 

Misuse of V or Q symbols: 

1. The function is pendent. DISPLAY STATE INDICATOR AND 
CLEAR AS REQUIRED. 

2 . Use of other than the function name alone in reopening 
a definition. 

3. Improper request for a line edit or display. 

The system variable D — ( for example, 010) has been set 
to an inappropriate value. 

Index value out of range. 

Attempt to share more variables than allotted quota. 
REQUEST LARGER QUOTA FROM APL OPERATOR. 



Execution was suspended within an APL statement. TO 
RESUME EXECUTION, ENTER A BRANCH TO THE STATEMENT 
INTERRUPTED. 

Shapes not conformable. 

Shared variable facility not in operation. 

Ranks not conformable. 

Transmission failure or more than the 
implementation-allowed number of characters entered in 
one line. RE-ENTER. IF CHRONIC, REDIAL OR HAVE TERMINAL 
OR PHONE REPAIRED. 

The state indicator (an internal list of suspended and 
pendent functions) has been damaged in editing a function 
or in performing a )COPY or ) ERASE. 

Invalid syntax; e.g. two variables juxtaposed; function 
used without appropriate arguments as dictated by its 
header; unmatched parentheses. 

Too many names used. SAVE, CLEAR, COPY 
or SAVE, CLEAR, SYMBOLS, COPY 
or ERASE, SAVE, CLEAR, COPY 

Fault in internal operation of the system. RELOAD. SEND 
TYPED RECORD, INCLUDING ALL WORK LEADING TO THE ERROR, TO 
THE SYSTEM MANAGER. 



Use of name which has not been assigned a value. 
A VALUE TO THE VARIABLE, OR DEFINE THE FUNCTION. 



ASSIGN 



Workspace is filled (perhaps by temporary values produced 
in evaluating a compound expression, or by values of 
Shared variables) . CLEAR STATE INDICATOR, ERASE NEEDLESS 
OBJECTS, OR REVISE CALCULATIONS TO USE LESS SPACE. 



Figure 2.1: Error Reports 



Section 2 : 



Fundamentals 



11 



A 


B C D E F G H 


I J 


KLMNOPQR 


S 


T U V W X I Z 






A 


B C D E F G H 


I I 


KLMNQPQR 


S 


nznn 









1 2 3 4 5 6 7 


8 9 












•• 


dieresis 





alpha 


V 


nor 


n+t 


V 




overbar 


r 


upstile 


H 


nand 


~ 


A 


< 


less 


L 


downstile 


f 


del stile 


V 


| 


< 


not greater 




underbar 


4 


delta stile 


A 


I 


= 


equal 


V 


del 


4> 


circle stile 


O 


I 


> 


not less 


A 


delta 


* 


circle slope 


o 


\ 


> 


greater 





null 


e 


circle bar 


o 




* 


not equal 


t 


quote 


® 


log 


o 


* 


V 


or 


u 


quad 


i 


I-beam 


1 


T 


A 


and 


( 


open paren 


¥ 


del tilde 


V 


~ 


- 


bar 


) 


close paren 


4 


base null 


JL 





T 


divide 


c 


open bracket 


f 


top null 


T 


o 


+ 


plus 


] 


close bracket 


\ 


slope bar 


\ 


- 


X 


times 


c 


open shoe 


/ 


slash bar 


/ 


- 


J> 


query 


3 


close shoe 


fi 


cap null 


n 





u 


omega 


n 


cap 


13 


quote quad 


r 


D 


e 


epsilon 


u 


cup 


j 


quote dot 


t 


, 


P 


rho 


i 


base 


B 


domino 


n 


♦. 


~ 


tilde 


T 


top 










+ 


up (arrow) 


1 


stile 










+ 


down (arrow) 


9 


semicolon 










i 


iota 


: 


colon 










o 


circle 


» 


comma 










* 


star 


, 


dot 










■+• 


right (arrow) 


\ 


slope 










■*- 


left (arrow) 


/ 


slash 
space 











Figure 2.2: The APL Character Set 





uu. 


< 

3 


< 

4 


5 


> 

6 


> 

7 


8 


V 

9 


A 

o 


+ 


• 
• 

X 


BACK 
SPACE 




-II 5 


— — y— 

(A) 

w 




P 
R 


T 


t 

Y 




I 
I 


O 

o 


* 
P 


.-► 


v RETURN 


L oc7^[a 


r 
s 


L 
D 


F 


V 


A 
H 


e 
J 


i 
K 


D 
L 


( 
E 


) 

] 


SHIFT 


c 
z 




n 
c 


U 
V 


± 


T 


1 
M 


• 


• 
* 

• 


\ 

/ 


SHIFT j 



Figure 2.3: Typical APL Keyboard 



12 APL Language 



Negative numbers are represented by an overbar immediately 
preceding the number, for example, "1.44 and 144E 2 are equivalent 
negative numbers. The overbar can be used only as part of a constant 
and is to be distinguished from the bar which denotes negation, as in 

-X. 

A single numerical constant entered by itself is accepted by the 
system as a scalar . A constant vector may be entered by listing the 
numerical components in order, separated by one or more spaces. A 
scalar character constant may be entered by placing the character 
between quotation marks, and a character vector may be entered by 
listing the characters between quotation marks. Such a vector is 
displayed by the system as the sequence of characters, with no enclosing 
quotes and with no separation of the successive elements. The quote 
character itself must be entered as a pair of quotes. Thus, the 
abbreviation of CANNOT is entered as x CAN xx T r and prints as CAN'T. 

SPACES 

The blank character is used primarily as a separator. The spaces 
that one or more blank characters produce are needed to separate names 
of adjacent defined functions, constants, and variables. For example, 
if F is a defined function, then the expression 3 F 4 must be entered 
with the indicated spaces. The exact number of spaces used in 
succession is of no importance, and extra spaces may be used freely. 
Spaces are not required between primitive functions and constants or 
variables, or between a succession of primitive functions, but they may 
be used if desired. For example, the expression 3+4 may be entered with 
no spaces. 

FUNCTIONS 

The word "function" derives from a word which means to execute or 
to perform. A function executes some action on its argument (or 
arguments) to produce a result which may serve as an argument to another 
function. For example: ~ ~" 



12 
14 
"2 



3x4 

2+(3x4) 

(-6)t3 



A function (such as the negation used above) which takes one 
argument is said to be monadic , and a function (such as times ) which 
takes two arguments is said to be dyadic . All APL functions are either 
monadic or dyadic or, in the case of defined functions only, niladic 
(taking no argument) . Certain of the special symbols are used to denote 
two different functions, one monadic and the other dyadic. For example, 
X-Y denotes s ubtraction of Y from X (a dyadic function) , and -Y denotes 
negation of I (a monadic function) . Other examples appear in Figures 
3 . 1 and 3.5. 

Each of the primitive functions is denoted by a single character 
or by an operator (discussed in Section 3) applied to such a character. 
For example, + and * are primitive functions as are +/ and * / (since / 
denotes an operator) . 



Section 2 : Fundamentals 1 3 



ORDER OF EXECUTION 

Parentheses are used in the familiar way to control the order of 
execution in a statement. Any expression within matching parentheses is 
evaluated before applying to the result any function outside the 
matching pair. 

In conventional notation, the order of execution of an 
unparenthesized sequence of monadic functions may be stated as follows: 
the (right-hand) argument of any function is the value of the entire 
expression to the right. For example, Log Sin Arctan x means the Log of 
Sin Arctan x, which means Log of Sin of Arctan x. In APL, the same rule 
applies to dyadic functions as well. Moreover, all functions, both 
primitive and defined, are treated alike; there is no hierarchy among 
functions (such as multiplication being done before addition or 
subtraction) . 

An equivalent statement of this rule is that an unparenthesized 
expression is evaluated in order from right to left. For example, the 
expression 3x8T3*|5-7 is equivalent to 3x(8["(3*(l(5-7)))). Their result 
is 27. A consequence of the rule is that the only substantive use of 
parentheses is to form the left argument of a function. For example, 
(12t3)x2 is 8 and 12*3*2 is 2. However, redundant pairs of parentheses 
can be used at will. Thus, 12* (3*2) is also 2. 

ARRAYS 

APL functions apply to collections of individual items called 
arrays . Arrays range from scalars, which are dimensionless, to 
multi-dimensional arrays of arbitrary rank and size. 

The vector is a simple form of array which may be formed by 
listing its elements as described in the discussion of constants. For 
example: 

V+2 35711131719 
A+ X ABCDEFGR X 

The elements of a vector may be selected by indexing . For example: 

F[3 1 5] 
5 2 11 

AlQ 5 14] 
HEAD 

Arrays of more complex structure may be formed with the reshape 
function denoted by p: 

M<-2 4p7 S+-2 UpA 

M B 

2 3 5 7 ABCD 

11 13 17 19 EFGH 

These results have two dimensions or axes and are called t able s or 
matrices . A matrix has two axes "and is said to be of rank 2 ; a vector 
has one axis and is of rank 1 . 

The left argument 2 4 in the foregoing examples specifies the 
shape of the resulting array. Arrays of arbitrary shape and rank may be 



1 >i APL Language 



produced by the same scheme. For example: 

T+2 3 Hp'ABCDEFGHIJKLMNOPQRSTUVWX x 

T 
ABCD 
EFGE 
IJKL 

MNOP 
QRST 
UVWX 

The shape of an array can be determined by the monadic function 
denoted by p : 

p7 pA? pT 

8 2 4 2 3 4 

Elements may be selected from any array (other than a scalar) by 
indexing in the manner shown for vectors, except that indices must be 
provided for each axis: 

M[2;3] T[2;l;4] 

17 P 

Ml 2 1;2 3 4] Tl2;l 2 3;1 2 3 4] 

13 17 19 MNOP 

3 5 7 QRST 

U7WX 

The indexing used in the foregoing examples is called 1 - origin 
because the first element along each axis is selected by the index i . 
One may also use o-origin indexing by setting the index v origin to o. 
The index origin is a system variable (See Section 4) denoted by 010. 
Thus: 

QI0+1 UIO+-0 

711 2 3] y[0 1 2] 

2 3 5 2 3 5 

3[2;3] B[l;2] 

G G 

All further examples assume i-origin unless otherwise stated. 

WORKSPACES AND LIBRARIES 

The common organizational unit in an APL system is the workspace . 
When in use, a workspace is said to be active , and it occupies a block 
of working storage in the central computer. Part of each workspace is 
set aside to serve the internal workings of the system, and the 
remainder is used, as required, for storing items of information and for 
containing transient information generated in the course of a 
computation. 

An active workspace is always associated with a terminal during a 
work session, and all transactions with the system are mediated by it. 
In particular, the names of variables (data items) and defined functions 
(programs) used in calculations always refer to objects known by those 
names in the active workspace; information on the progress of program 
execution is maintained in the state indicator of the active workspace; 
and control information affecting the form of output is held within the 
active workspace. 



Section 2 : Fundamentals 1 5 



Inactive workspaces are stored in libraries , where they are 
identified by arbitrary names. They occupy space in secondary storage 
facilities of the central computer and cannot be worked with directly. 
When required, copies of stored workspaces can be made active, or 
selected information may be copied from them into an active workspace. 

Libraries are either private or public . Private libraries are 
associated with individual users of the system, and are identified by 
the user's account number. Access to them by other users is restricted 
in that one user may not store workspaces in another person's library, 
nor obtain a listing of the workspaces already stored there. However, 
one user may activate a copy of another user's unlocked workspace if he 
knows the library number and workspace name. Workspaces and libraries 
are managed by system commands as described in Section 8 . 

NAMES 

Names of workspaces, functions, variables, and groups (see Section 
8) may be formed of any sequence of alphabetic and numeric characters 
that starts with an alphabetic and contains no blank. 

The environment in which APL operations take place is bounded by 
the active workspace. Hence, the same name may be used to designate 
different objects (that is, groups, functions, or variables) in 
different workspaces, without interference. Also, since workspaces 
themselves are never the subject of APL operations, but only of system 
commands, it is possible for a workspace to have the same name as an 
object it holds. 

Stored workspaces and the information they hold can be protected 
against unauthorized use by associating a lock , comprising a colon and a 
password of the user's choice, with the name of the workspace, when the 
workspace is stored. In order to activate a locked workspace or copy 
any information it contains, a colon and the password must again be 
used, as a key , in conjunction with the workspace name. Listings of 
workspace names, including those in public libraries, never give the 
keys, and do not overtly indicate the existence of a lock. 

USER IDENTIFICATION 

Account numbers can be similarly protected by locks and keys, thus 
maintaining the security of a user's private library and avoiding 
unauthorized charges against his account. Passwords for locks and keys 
may be formed of any sequence of alphabetic and numeric characters . In 
use as either a lock or key, a password follows the number or name it is 
protecting, from which it is set off by a colon. 

APL systems differ in the procedure required to sign-on or begin a 
session. However, a numerical identification of the user is usually 
provided in some manner, so that it can be used to specify the first 
element of DAI. 



16 APL Language 



SECTION 3: PRIMITIVE FUNCTIONS AND OPERATORS 



The primitive functions fall in two classes, scalar , and mixed . 
Scalar functions are defined on scalar arguments and are extended to 
other arrays item-by-item. Mixed functions are defined on arrays of 
various ranks and may yield results which differ from the arguments in 
both rank and shape. Five primitive operators apply to scalar dyadic 
functions and to certain mixed functions to produce a large number of 
new functions. 

The definitions of certain functions depend on certain system 
variables whose names begin with the symbol Q (as in QIO and UCT) . 
These system variables are discussed further in Section 4. 

SCALAR FUNCTIONS 

A monadic scalar function extends to each item of an array 
argument; the result is an array of the same shape as the argument and 
each item of the result is obtained as the monadic function applied to 
the corresponding item of the argument. 

A dyadic scalar function extends similarly to a pair of arguments 
of the same shape. To be conformable, the arguments must agree in 
shape, or at least one of them must be a scalar or one-element vector. 
If one of the arguments has only one item, that item is applied in 
determining each element of the result. For example: 

1 2 3x4 5 6 
4 10 18 

3 + U 5 6 
7 8 9 

2 3+4 5 6 
LENGTH ERROR 

Each of the scalar functions is defined on all real numbers with 
two general exceptions: the four boolean functions are defined only on 
the numbers o and l, and the functions = and * are defined on characters 
as well as numbers. Specific exceptions (such as 4-fO) will be noted 
where appropriate . 

The scalar functions are summarized in Figure 3.1 together with 
their symbols and brief definitions or examples which should make their 
use clear. The remainder of this section is devoted to more detailed 
definitions. 

A dyadic function f may possess a left identity element L such 
that L f X equals X for any J, or a right identity element R such that 
X f R equals X. For example, one is a right identity element of * since 
XtI is X, zero is a left or right identity of +, one is a left or right 
identity of x , and the general logarithm function ® has no identity 
element. 

Identity elements become important as the appropriate result of 
applying a function over an empty vector; for example, the sum over an 
empty vector is 0, (the identity element of +) , and the product over an 
empty vector is 1, the identity element of x. These matters are 
discussed further in the treatment of the reduction operator which 
concerns such applications of dyadic functions over vectors. 

Figure 3.2 lists the identity elements of the dyadic scalar 
functions. The relational functions <, £, =, £, > and * possess no true 
identity elements, but do when considered as boolean functions, that is, 

i 
Section 3 : Primitive Functions and Operators 1 7 



Monadic form ffl 



Dyadic form AfB 



Definition 
or example 



Name 



Name 



Definition 
or example 



+B IS B 

-B is 0-B 

xB is (B>0)-B<0 

*B is ltB 

|~3.14 is 3 .14 



B 


LB 


rs 


3. 14 
"3.14 


3 

~4 


4 
"3 



?B is Random choice 
from iB 

*B is (2 .71828. . )*B 

»*N is W is *«N 

OB is Bx3 . 14159 . . . 



!0 is 1 

!B is Bx!B-l 

or IB is Gamma (B+l) 



"1 is 



'0 is l 



Conjugate 

Negative 

Signum 

Reciprocal 

Magnitude 

Floor 

Ceiling 

Roll 

Exponential 

Natural 
logarithm 

Pi times 
Factorial 

Not 



{-A)QB 


A 


4 OB 


(1-B*2)* . 5 





(1-3*2)*. 5 


Arcs in B 


1 


Sine B 


Arccos B 


2 


Cosine B 


Arctan B 


3 


Tangent B 


("l+B*2)*.5 


4 


(1+B*2)*.5 


Arsinh B 


5 


Sinh B 


Arcosh B 


6 


Cosh B 


Artanh B 


7 


Tanh B 



Table of Dyadic o Functions 



Plus 

Minus 

Times 

Divide 

Residue 

Minimum 

Maximum 

Deal 

Power 

General 
logarithm 



2+3. 2 IS 5.2 

2-3 .2 is "1.2 

2x3.2 is 6.4 

2*3 . 2 is .625 

A \B is B-A-*LB*A+A = 

3L7 is 3 

3T7 is 7 

A Mixed Function (See 
Figure 3.5) 

2*3 is 8 

A»B is Log B base A 
A®B is (&B)t®A 



Circular, Hyperbolic, Pythagorean 
(See table at left) 



Binomial 



And 
Or 

Nand 
Nor 



Less 

Not greater 

Equal 

Not less 

Greater 

Not Equal 



A\B is (!B)*(!i4)x!B-i4 
2!5 is 10 3!5 is 10 



AVB 



A 


B 


AAB 


AVB 


A«B 














1 





1 





1 


1 


1 








1 


1 


1 


1 


1 


1 






Relations 

Result is 1 if the 
relation holds , 
if it does not: 

3<7 is 1 

7<3 is 



Figure 3.1: Primitive Scalar Functions 



1 8 APL Language 



when restricted to the domain 
included in the figure. 



and i. These identity elements are 



Dyadic 




Identity 


Left- 


Function 




Element 


Right 


Plus 


< 





L R 


Minus 


- 





R 


Times 


X 


1 


L R 


Divide 


■f 


1 


R 


Residue 


1 





L 


Minimum 


L 


(note 1 ) 


L R 


Maximum 


r 


(note 2) 


L R 


Power 


* 


1 


R 


Logarithm 


® 




None 


Circle 


o 




None 


Binomial 


1 


1 


L 


And 


A 


1 


L R 


Or 


V 





L R 


Nand 


i\ 




None 


Nor 


¥ 




None 


Less 


< 


\ Apply 


L 


Not greater 


< 


1 I for 


L 


Equal 


= 


1 \ boolean 


L R 


Not less 


> 


l ( arguments 


R 


Greater 


> 


\ only 


R 


Not equal 


£ 


o) 


L R 



Note 1 : the largest representable 
number 

Note 2 : the greatest in magnitude 
of representable negative numbers 



Figure 3.2: 



Identity Elements of 
Primitive Scalar 
Dyadic Functions 



PLUS, MINUS, TIMES, DIVIDE AND RESIDUE 

The definitions of the first four of these functions agree with 
the familiar definitions except that the indeterminate case 0*0 is 
defined to yield the value 1. For X*o , the expression ;sr*0 evokes a 
domain error. 

If A and B are positive integers, then the residue A\B is the 
remainder on dividing A into B. The following definition covers all 
values of A and B: 



If A=0 , then A\B equals B 

If A*Q, then A\B lies between A and zero (being permitted to equal 

zero but not A) and is equal to B-N*A for some integer N. 

For example: 



1| 2.385 



I 5, 



0.385 



5.8 



12 



3 I 3 2 10123 
"1 ~2 "1 
3|~3 "2 "1 1 2 3 
12 



Section 3 : Primative Functions and Operators 1 9 



CONJUGATE, NEGATIVE, SIGNUM, RECIPROCAL, MAGNITUDE 

The conjugate function +x yields its argument unchanged, the 
negative function -X yields the argument reversed in sign, and the 
reciprocal *X is equivalent to nx. For example, if x«-4 ""5, then: 

+X -X iX 

4-5 "4 5 0.25 "0.2 

The result of the sign urn function *x depends on the sign of its 
argument, being "1 if x<0 , and if 1=0, and l if x>0. The magnitude 
function \X (also called absolute value ) yields the greater of X and -X; 
in terms of the signum function it is equivalent to XxxX. For example: 

x~3 4 |"3 4 

10 1 3 4 

BOOLEAN AND RELATIONAL FUNCTIONS 

The boolean functions and , or , nand (not-and) , and nor (not-or) 
apply only to boolean arguments, that is, and 1; if is interpreted 
as false , and 1 as true , then the definitions of these functions are 
evident from their "names. For example, ,4 AS (read as A and B) equals 1 
(is true ) only if A equals 1 (is true ) and B equals 1. All cases are 
covered by the following examples: 

A+0 Oil 

fl+0 10 1 

A*B avB A*B A*B 

0001 0111 1110 1000 

The monadic function not yields the logical complement of its 
argument, that is ~0 is 1, and ~l is 0. 

The relational functions apply to any numbers, but yield only 
boolean results, that is or 1. The result is l if the indicated 
relation holds, and otherwise. For example: 

3 5<5 3 3 5 7*7 5 3 

10 10 1 

The comparisons involved in determining the results of the 
relational functions are not absolute, but are made to a certain 
tolerance specified by the comparison tolerance OCT. Two scalar 
quantities A and B are considered to be equal if the magnitude of their 
difference does not exceed the value of UCT multiplied by the larger of 
the magnitudes of A and B, that is, if (\A-B) is less than or equal to 
Uct*{ u>r |s. 

Similarly, A>B is considered to be true if (.A-B) is greater than 
or equal to -QCTx( U)f( |B) , and A>B is considered true if AZB is true 
and A=B is not. 

The comparison tolerance OCT is typically set to the value 1S~13. 
The setting OCT+Q is also useful since it yields absolute comparisons, 
but may lead to unexpected results due to the finite precision of the 
representation of numbers. For example, if the maximum precision is 16 



20 APL Language 



decimal digits and all digits are displayed in printing, then: 

QCT+O 

X 
0.6666666666666667 

Y-f-3x* 

1-2 
2.2204460'+9250313£' 16 

2 = 1 


0CT+1E 13 

2 = Y 
1 

When applied to boolean arguments only, the relations are, in 
effect, boolean functions, and denote functions which may be familiar 
from the study of logic, although referred to by different names and 
symbols. For example, X*Y is the exclusiye- or of X and Y, and XzY is 
material implication . This association should" be clear from the 
following table, which lists in the first two columns the four possible 
sets of values of two boolean arguments, and in the remaining columns 
the values of the 16 possible boolean functions, with the symbols of the 
boolean and relational functions of APL appended to appropriate columns : 

A B A f B 

0000000011111111 

01 0000111100001111 

10 0011001100110011 

11 01010101010 10101 

A > < * V V = £ <. *< 

The ten functions listed at the foot of this table embrace all 
non-trivial boolean functions of two arguments. Consequently, any 
boolean expression of two arguments X and Y can be replaced by a simple 
APL expression as follows: evaluate the expression for the four 
possible cases, locate the corresponding column in the table, then use 
the function symbol at the foot of the column, or, if none occurs, use X 
or Y or ~X or ~Y or or 1 as appropriate. 

MINIMUM AND MAXIMUM 

The functions denoted by L and r perform as expected from their 
names. For example: 

X+~3 "2 "1 0. 1 2 3 

Y+-3 2 1 "1 "2 "3 

X[Y 
3 2 10 12 3 

XlY 
"3 2 "1 "1 "2 ~3 

FLOOR AND CEILING 

The floor function L yields the integer part of its argument, that 
is, IX yields the largest integer which does not exceed X. Similarly, 
[X yields the smallest integer which is not less than X. For example: 

X-f-~3.lt 2.718 

IX \X 

~4 2 "3 3 

"4 2 ~3 3 

.Section 3: Primative Functions and Operators 21 



The ceiling and floor functions are affected by the comparison 
tolerance OCT as follows: if there is an integer I for which \X-I does 
not exceed the value of OCT, then both IX and {X equal I. For example, 
if results are represented and printed to 16 decimal digits, then: 



J«-3x2*3 






QCT+1E~13 




ncT+o 


IX 


2 


IX 


[X 


3 


\X 



ROLL (Random number function) 

The roll is a monadic function named by analogy with the roll of a 
die; thus ?6 yields a (pseudo-) random choice from i"6, that is the first 
six integers beginning- with either or l according to the value of the 
index, origin UIO. For example: 

UI0+-1 

? 6 ? 6 ? 6 

15 3 

?6 666666666666 
4215563 4 5 114 5 

UIO+O 

? 6666666666666 
0202435 5 30324 

The domain of the roll function is limited to positive integers. 

The roll function employs an algorithm due to D.H. Lehmer; the 
result for each scalar argument X is a function of X and of the random 
link variable URL. The result of the roll function is system dependent 
but typically for X<2*31 is equal to UIO plus the integer part of 

X*URL*~1+2*31. 



POWER, EXPONENTIAL, GENERAL AND NATURAL LOGARITHM 

For non-negative integer right arguments the power function X*N is 
simply defined as the product over N repetitions of X. It is 
generalized to non-positive and non-integer arguments so as to preserve 
the relation that X*A+B shall equal (X*A )x(X*B ) . Familiar consequences 
of this extension are that x*-N is the reciprocal of X*N, and x**N is 
the Nth root of X. For example: 

2*~3 "2 "1 1 2 3 
.125 .25 .51248 

64**1 2 3 4 5 6 
64 8 4 2.828 2.297 2 

The indeterminate case 0*0 is defined to have the value l. 

The domain of the power function X*Y is restricted in two ways: 
if Z=0, then Y must be non-negative; if X<0, then Y must be an integer 
or a (close approximation to a) rational number with an odd denominator. 
For example, ~8*.5 yields a domain error, but ~8*1*3 and ~8*2*3 yield ~2 
and 4, respectively. 

The exponential function *X is equivalent to the expression e*X, 
where e is the base of the natural logarithms, approximately 2, .71828. 



22 APL Language 



For example: 

*~2 "10 12 
0.1353352832 . 367 879441 2 1 2.718281828 7.389056099 

The natural logarithm function ®X is the inverse of the 
exponential, that is, *®X and ®*X both equal X. For example: 

• 1 2 3 4 
0.6931471806 1.098612289 1.386294361 

r *®l 2 3 4 
12 3 4 

«*1 2 3 4 
12 3 4 

The domain of the natural logarithm function is limited to 
positive numbers. 

The general logarithm function B*X is defined as (®X)*®B. It is 
inverse to the power function in the following sense: B*B*X and B®B*X 
both equal X. Limitations on the domain follow directly from the 
defining expression. 

CIRCULAR, HYPERBOLIC, AND PYTHAGOREAN FUNCTIONS 

The symbol o denotes a monadic function whose result equals pi 
times its argument. For example: 

oi 2 .5 
3.141592654 6.283185307 1.570796327 

The symbol o is also used dyadically to denote a family of fifteen 
related functions as follows: the expression iox is defined for integer 
values of I from "7 to 7, and is in each case equivalent to one of the 
circular, hyperbolic, or pythagorean functions as indicated in Figure 
3.1. 

The arguments for the circular functions Sin, Cos, and Tan (iox, 
2oX, and 3oz) are in radians. For example: 

PJ-HDl 

10PI*2 3 4 
1 0.8660254038 0.7071067812 

The hyperbolic functions sinh and cosh are the odd and even 
components of the exponential function ; . that is, 5oX is odd, 60* is 
even, and the sum (5oZ)+(6oZ) is equivalent to *X. Consequently: 

5oX equals . 5x(*X) -i*-X) 
&oX equals . 5x( *X)+(*-X) 

The definition of the hyperbolic tangent is analogous to that of the 
tangent, that is, 7ox equals (5oX)*6oX. 

The. three pythagorean functions oox, 4ox, and ~4oX are defined as 
in Figure 3.1, and are related to the properties of a right triangle as 



Section 3: Primative Functions and Operators 23 



indicated in Figure 3.3. They may also be defined as follows: 



"40X equals 
oox equals 
40X equals 



50 
20 
6O 



6 OX 
'lox or 

'50X 



10 20X 



1 A >^ 




E 

D 

AC-\ 
AB=OOBC 
BC=OOAB 
AE=^ODE 
DE- koAE 


I B 



The Pythagorean Functions 
Figure 3.3 



Each of the family of functions lox has an inverse in the family, 
that is, (-I)oX is the inverse of lox. Certain of the functions are not 
monotonic, and their inverses are therefore many-valued. The principal 
values are chosen in the following intervals: 



Arcosh 


i?«-~60X 


i?S0 




R+ 4oX 


J? 2 


Arccos 


R+ 2 ox 


(i?S0)A(i?<Ol) 


Arc sin 


R*- lox 


( |fl)<o.5 




R+- OOX 


i?20 




f?«- 4 OX 


i?>0 



FACTORIAL AND BINOMIAL FUNCTIONS 

For positive integer arguments, the factorial function \N is 
defined as the product of all positive integers up to N. An important 
consequence of this definition is that IN equals ffx'.jy-i, or, 
equivalently IN-l equals (IN)*N. This relation is used to extend the 
function to non-integer and negative arguments. For example: 

ff+1 2 3 4 5 

IN 
1 2 6 24- 120 

( IN)*N 
1 1 2 6 24 

!0 1 2 3 4 
1 1 2 6 24 

Ft- . 5 1 1.5 2 2.5 

IF 
0.8862269255 1 1.329340388 2 3.32335097 

( \F)iF 
1.772453851 1 0.8862269255 1 1.329340388 

!~.5 .5 1 1.5 
1.772453851 1 0.8862269255 1 1.329340388 

This extension leads to the expression (ro)*0, or 1*0 for ! "1 , and 
"1 is therefore excluded from the domain of factorial, as are all 
negative integers. 



24 APL Language 



The binomial function M\N is defined, for non-negative integer 
arguments, as the number of distinct ways in which M things can be 
chosen from N things. The expression ( \N)i ( !M)x( IN-M) yields an 
equivalent definition which is used to extend the definition to all 
numbers. Although the domain of factorial excludes negative integers, 
the domain of the binomial does not, since any implied division by zero 
in the numerator \N is invariably accompanied by a corresponding 
division by zero in the denominator; the function therefore extends 
smoothly to all numbers. 

The result of UN is equivalent to coefficient I in the binomial 
expansion (X+1)*N . For example: 

1 2 3 !3 
13 3 1 



OPERATORS 

An operator may be applied to a function to yield a different 
function. For example, the outer product operator denoted by the 
symbols ° . may be applied to any of the primitive scalar dyadic 
functions to produce a corresponding "table function" as illustrated 
below for times and power ; 



A+l 2 3 
A° . xA 
2 3 4 

i+6 8 

6 9 12 

8 12 16 



A» .*A 

111 

4 8 16 

9 27 81 

16 64 256 



Four of the APL operators - reduction , scan , inner product , and 
outer product - apply to any primitive scalar dyadic function. The axis 
operator applies to reduction and scan , and also to certain of the 
mixed functions. 

REDUCTION 

Reduction is denoted by the symbol / and applies to the function 
which precedes it. For example, if V+-1 2 3 4 5, then +/V yields the sum 
of the items of V, and x/7 yields their product: 



t/V 



x/P 



15 



120 



In general, an expression of the form f/V is equivalent to the 
expression obtained by placing the function symbol f between adjacent 
pairs of items of the vector V: 



r/v 

-/V 



ir2r3T4r5 

1-2-3-4-5 



The last example points up the fact that the general rule for the 
order of execution is applied, and that as a consequence the expression 
-/V yields the alternating sum of the items of V. The alternating sum 
is defined as the sum obtained after first weighting the items by 



Section 3: Primative Functions and Operators 25 



multiplying alternate elements by l and l . Thus : 

A+l ~1 1 "1 1 
VxA 
12 3 4 5 
+ /VxA 



■IV 



3 
3 
Similarly, r/V yields the alternating product ; 

V*A 
1 .53 .25 5 

x/V*A 
1.875 

*/V 
1.875 

The result of applying reduction to any scalar or vector is a 
scalar; the value in the case of a scalar or one-element vector argument 
is the single item itself. The application of reduction to other arrays 
is treated in the discussion of the axis operator. 

Reduction of an empty vector by any function is defined as the 
identity element of the function if one exists, i&§> a domain error if 
not. Thus if V is an empty vector, +/V equals 0, and a/7 equals 1. 

The reason for this definition is the extension to empty vectors 
of an important relation between the reductions of two vectors P and Q 
and the reduction of the vector V+P.Q obtained by chaining them 
together. For example: 

+/7 equals (+/P) + (+/<2) 
x-/V equals (x/p)x(x/Q) 

If P is an empty vector it is clear that +/P must equal (the identity 
element of +) , and that x/p must equal 1. 

SCAN 

The scan operator is denoted by the symbol \ and applies to the 
function which precedes it. When the resulting function is applied to a 
vector V it yields a vector of the same shape whose Kth element is equal 
to the corresponding reduction over the first K elements of V. For 
example : 

+\1 2 3 4 5 
1 3 6 10 15 

x\l 2 3 4 5 
1 2 6 24 120 

V\0 10 1 
111 

A\l 10 10 

110 

<\0 10 110 
10 

The extension of scan to arrays other than vectors is treated in 
the discussion of the axis operator. 



26 APL Language 



AXIS 

Since reduction is defined on vectors, and since a matrix can be 
conceived as a collection of row vectors, the result of reduction on a 
matrix could be defined as the vector of results obtained by reduction 
of each of the row vectors. However, a matrix can also be viewed as a 
collection of column vectors, and reduction could be defined 
accordingly. It is therefore important to be able to specify which set 
of vectors is to be reduced. 

The row vectors extend along the second axis of the matrix, and 
are each of length equal to the length of that axis. Similarly, the 
column vectors extend along the first axis and, in general, the index of 
an axis identifies a set of vectors in an array of any non-zero rank. 

The axis operator is denoted by brackets enclosing an expression 
which yields the index of an axis as a one-element vector or a scalar. 
It determines the direction of application of any scan or reduction 
operator whose symbols immediately precede it. For example: 

M-e-3 4pil2 +\[1]M +\[2]M 

1234 1234 136 10 

5/678 6 8 10 12 5 11 18 26 

9 10 11 12 15 18 21 24 9 19 30 42 

+/111M 
15 18 21 24 

+/L21M 

10 26 42 

The shape of the result of scan equals the shape of the argument. 
The shape of the result of reduction equals the shape of the argument 
except that the indicated axis of reduction is removed. The indexing of 
axes depends on the index origin 010. 

If no axis operator occurs, reduction and scan apply along the 
last axis. The symbols / and \ also denote reduction and scan, but in 
the absence of axis operators they apply along the first axis . 

The axis operator is also used to specify the axis of application 
of the mixed functions reverse , rotate , compress , and expand . 

INNER PRODUCT 

If P and Q are vectors of the same' shape, then the expression 
+/PxQ has a variety of useful interpretations. For example, if P is a 
list of prices and Q a list of corresponding order quantities, then 
+/PxQ is the total cost. Expressions of the same form employing 
functions other than + and x are equally useful, as suggested by the 
following examples (where B is used to denote a boolean vector} : 

a/P=Q Comparison of P and Q. 

+/P=Q Count of agreements between P and Q. 

l/P+Q Minimum distance for shipment, where P represents the 
distances from source to transhipment points and Q the 
distances from these points to the destination. 

+/PxB Sum over a subset of P specified by B. 

*/P*B Product over a subset of P specified by B. 

The inner product produces functions equivalent to expressions in 
this form; it is denoted by. a dot and applies to the two functions which 
surround it. Thus P+.xQ is equivalent to +/Px#, and Px.*B is equivalent 

Section 3: Primative Functions and Operators 27 



to x/p*p, and, in general, Pf.gC is equivalent to f/PgQ, if P and Q are 
vectors. 

The inner product is extended to arrays other than vectors along 
certain fixed axes, namely the last axis of the first argument and the 
first axis of the last argument. The lengths of these axes must agree. 
The sh ape of the result is obtained by deleting these axes and chaining 
the remaining shape vectors together. The consequence for matrix 
arguments is illustrated in Figure 3.4. The consequences for the shape 
of inner products on some other arrays are illustrated below: 

Q.G Q.H 
7 7 



( scalar ) 

pGf.gH 



Q.A B.S. 
3 5 ^5 2 7 


7 9 9 

1 ^ 


3 2 7 
pAf.gB 


7 

pCf .go 




pEf.gF 



Formally, pAf.gB equals ( 1+pA) ,1+pB. 

The inner product M+.*N is commonly called the matrix product. 
Examples of it and other inner products follow: 



P«-2 3 5 7 

M W+ . xM 

1111 1234 
0111 0123 
0011 0012 
0001 0001 



M+.*P 
17 15 12 7 



P+ . x-M 

2 5 10 17 



MA.=Af 
1 




Px . *M 
2 6 30 210 



M- . xM 
1 _0 1 _0 
10 1 
1 _o 

1 



MA. 
10 



= 0011 




Figure 3.4: Inner Product 



28 APL Language 



Either argument of an inner product may be a scalar; it is 
extended in the usual manner. For example, A+.*l is equivalent to 
+ /A, and l+.xA is equivalent to +/A. 

OUTER PRODUCT 

The outer product operator, denoted by the symbols °. preceding 
the function symbol, applies to any dyadic primitive scalar function, 
so that the function is evaluated for each member of the left argument 
paired with each member of the right argument. For example, if 
ii-f-1 2 3 and S-e-l 2 3 4 5: 



A" . xB 
12 3 4 5 

2 4 6 8 10 

3 6 9 12 15 



Ao ,<B 
1111 
111 
11 



Such tables may be better understood if labelled in a way widely used in 
elementary arithmetic texts: values of the arguments are placed beside 
and above the table, and the function whose outer product is being 
computed is shown at the corner. Thus: 









B 














B 








* 1 


1 
1 


2 
2 


3 
3 


4 
4 


5 
5 




< 1 


1 


2 




3 


4 


5 


1 1 




1 1 





1 




1 


1 


1 


2 1 


2 


4 


6 


8 


10 


A 


2 1 










1 


1 


1 


3 1 


3 


6 


9 


12 


15 




3 1 













1 


1 



In the foregoing example the shape of the result A°.*B is clearly 
equal to (piO.(pS). This expression yields the shape for any arguments 
A and B. Thus if R+-A°.+B and A is a matrix of shape 3 4 and B is a 
three-dimensional array of shape 5 6 7, then R is a five-dimensional 
array of shape 3 4 5 6 7. Moreover, RH ;J ;K;L;M1 equals ALI;J1+BLK;L ;Ml 
for all possible values of the indices. 

MIXED FUNCTIONS 

The mixed functions are grouped in five classes according to 
whether they concern the structure of arrays , selection from arrays , the 
generation of selector information for use by selection functions, 
numerical calculations, or transformations of data such as that between 
characters and numbers. All are listed in Figure 3.5 together with 
brief definitions or examples. 

Those functions which may be modified by an axis operator may also 
be used without an axis operator, in which case the axis concerned is 
the last, or, in the case of the functions denoted by e and by /, the 
first. 



Section 3: Primative Functions and Operators 29 



Name 


Sign 


Definition or example 


Shape 
Reshape 

Ravel 

Reverse 

Rotate s 

Catenate 

Transpose 3 


pA 
VqA 

,A 

$A 

Ai>A 

A, A 
VQA 

QA 


p p is n p e is 3 4 p5 is i0 

Reshape a to dimension v 3 4pil2 is E 
12pE is 112 OpE is i0 

,A is (y./pA)pA ,E is il2 p,5 is 1 

DCS A IJKL 

W is HGFE *[1]X is ex is EFGH 

LKJI $P is 7 5 3 2 /1BCD 

3<t>P is 7 2 3 5 is ~l<t>f> 1 ~1(|>X is SFGH 

P,i2 is 235712 <T','HIS' is 'THIS' 

AEI 
Coordinate I of 4 2 IS)* is BFJ 
becomes coordinate CGK 
VLI] of result i i$£ is l 6 ll DHL 

Reverse order of coordinates §E is 2 lS)ff 


Take 
Drop 

Compress 

Expand 
Indexing 


V+A 
V\A 

VIA 

V\A 

VIA1 

MIA; A] 

ALA;. . 
..;4] 


} Take or drop |f[I] first 2 3+X is 4SC 
> (Vlllzo) or last (F[I]<0) EFG 
) elements of coordinate j ~2+P is 5 7 

1 3 
10 1 0/P is 2 5 10 1 0/E is 5 7 

9 11 
1 1/[1]£ is 1 2 3 1+ is 1 HE 
9 10 11 12 

A BCD 
1 l\i2 is 102 1011 1\X is E FGH 

I JKL 
P[2] is 3 P'[ 4 3 2 1] is 7 5 3 2 

E[l 3;3 2 1] is 3 2 1 
11 10 9 
E[l;] is 1 2 3 4 .4BCD 
E[;l] is 1 5 9 ' ABCDEFGHIJKL' [E] is EPfffl 


Index: 
generator 

Index of 

Membership 

Grade up * 
Grade down 
Deal" 


\S 
V\A 

AeA 

kv 
yv 
s?s 


First s integers it is l 2 3 4 

i0 is an empty vector 

Least index of A Pi 3 is 2 5 12 5 

in v, or l+pf PxE is 3 5 4 5 

4 4l4 is 1 5 5 5 5 

110 
pWeY is B W EsP is l o 1 

Peil is 1 1 0000 

■) The permutation which A3532is4l32 

Would order v (ascend- 

) ing or descending) f3 532 is 2134 

W?X is Random deal of w elements from iY 


Matrix 
inverse 

Matrix 
division 

Decode 

Encode 


SM 
MMM 

AxA 
ATA 


B2 2pl 1 1 is l ~i arguments may 

1 be scalars, 
(2 2pP)@2 2pl l o l is ~3 "4 vectors, or 

5 7 matrices 

1011 7 7 6 is 1776 24 60 60ll 2 3 is 3723 

24 60 60T3723 is 1 2 3 60 60T3723 LB 2 3 


Execute 

Format , 
monadic 

Format , 
dyadic 


i.V 
VIA 


l'lt2' is 3 i'P' is 2 3 5 7 

'~1 .5'a.=t~1 . 5 is 1 

pTE is 3 12 X is jX 

UP is 4 1TP is 2.0 3.0 5.0 7.0 

~1TP is 6 "lfP is 2E00 3E00 5E00 7EO0 



Notes to Figure 3.5 



1 . Restrictions on 
argument ranks are 
indicated by: S for 
scalar, V for vector, 
M for matrix, and A 
for any array. 
Except as the left 
argument of Si A or 
SZA1 , or the argument 
of -i and t, a scalar 
may be used in place 
of a vector. A 
one-element vector 
may replace any 
scalar. 

2. Arrays used in 
examples: 

P 
2 3 5 7 

E 

12 3 4 

5 6 7 8 

9 10 11 12 

X 
ABCD 
EFGH 
IJKL 

3. Function depends 
on index origin. 

t. Elision of any 
index selects all 
along that axis. 

5. The function is 
applied along the 
last axis; the 
symbols 1, \, and e 
are equivalent to /, 
\, and if, 

respectively, except 
that the function is 
applied along the 
first axis. In 
general, the relevant 
axis is determined by 
[VI after the 
function symbol. 



Figure 3.5: Primitive Mixed Functions 



30 APL Language 



A scalar may be used in place of a one-element vector: 

a. as left argument of 

reshape 3 pit -*--* (,3)p^ 

take 3 -M 5 ■*--»■ ( , 3 ) 1 1 5 

drop 34-i5 «-»■ ( , 3 ) + 1 5 

expand 1 \ . 5 ■<--»■ ( , 1 ) \ , 5 

transpose IS?, 5 ■*■■*■ (,1)<?,5 

format 5f3.2 +•+ (,5)T3.2 «-+ 5 T3.2 

b. as right argument of 

execute *'P' ■*■+ 4,'P 1 
branch -»-4 ■<-•*• '-*-,4 

A scalar is extended to conform to a vector: 

a. as left argument of 

compress 1/ i3 ++ 1 1 1 / i3 
rotate l<t>2 2 pit +■-* 1 1 <J> 2 2pi<+ 

b. as right argument of 

compress 101/2 •*-->■ 101/222 

expand 1 1 \ 2 «--*• 1 1 \ 2 2 

A one-element vector is permitted in place of a scalar: 

a. as left argument of 

deal (,3)?5 ++ 3?5 

b. as right argument of 

index generator i , 5 ■*--+ i 5 
deal 3?, 5 •*--* 3?5 



Figure 3.6: Scalar-Vector Substitutions for Mixed Functions 



Figure 3.5 gives restrictions, in summary form, on the ranks of 
arguments which may be used with each mixed function. Figure 3.6 shows 
for what mixed functions and under what conditions scalar and vector 
arguments may be substituted for each other. 



STRUCTURAL FUNCTIONS 

In the monadic structure functions the argument may be of any 
type, numeric or character. In the dyadic selection and structure 
functions one argument may be of any type and the other (which serves as 
an index or other selection indicator) must be numeric, and xn two cases 
(compression and expansion) is further restricted to be boolean. 

Shape Reshape and Ravel 

The monadic function p applied to an array A yields the shape of 
A, that is, a vector whose components are the dimensions of A. For 

Section 3: Primative Functions and Operators 31 



example, if A is the matrix 



2 3 

6 7 

10 11 



12 



of three rows and four columns, then pA is the vector 3 4. 

Since pA contains one component for each axis of A, the expression 
ppA is the rank of A. Figure 3.7 illustrates the values of pA and ppA 
for arrays of rank o (scalars) up to rank 3. In particular, the 
function p applied to a scalar yields an empty vector . 



Type of Array 


pA 


ppA 


pppA 


Scalar 
Vector 
Matrix 
3-Dimensional 


N 
M N 
L M N 




1 
2 
3 


1 

1 
1 

1 



Figure 3.7 SHAPE AND RANK VECTORS 

The monadic function ravel is denoted by a comma; when applied to 
any array A it produces a vector whose elements are the elements of A in 
row order. For example, if A is the matrix: 



2 

10 
18 



4 
12 
20 



6 
14 
22 



16 
24 



and if V+,A , then V is a vector of dimension 12 whose elements are the 
integers 2 4 6 8 10 12 ... 24- If A is a vector, then ,A is 
equivalent to A; if A is a scalar, then ,A is a vector of length l. 

The dyadic function p reshapes its right argument to the shape 
specified by its left argument. If M+DpV, then M is an array of 
dimension D whose elements are the elements of V. For example, 
2 3p 123456 is the matrix 



If n, the total number of elements required in the array DpV, is 
equal to the dimension of the vector V, then the ravel of DpV is equal 
to V. If N is less than pv , then only the first N elements of V are 
used; if N is greater than pV , then the elements of V are repeated 
cyclically. For example: 



2 3pl 2 
2 1 
1 2 



3 3pl 
10 
10 
1 



More generally, if A is any array, then DpA is equivalent to Dp ,A- 
For example: 



A 
12 3 
4 5 6 



3 5pA 
2 3 4 
12 3 
6 12 



The expressions OpX and o 3pX and o OpJ are all valid; any one or 
more of the axes of an array may have zero length. Such an array is 
called an empty array . If D is an empty vector, then DpA is a scalar. 



32 APL Language 



Reverse and Rotate 

The monadic function reverse is denoted by <|> ; if x is a vector and 
K+QX , then k is equal to x except that the items appear in reverse 
order. The axis operator applies to reversal and determines the axis 
along which the vectors are to be reversed. For example: 

A $[114 <t>[2lU 

123 H56 321 

456 123 6 5 4 

The expression $A denotes reversal along the last coordinate of A , 
and ba denotes reversal along the first coordinate. For example, if A 
is of rank 3, then $A is equivalent to <$[3]A , and qA is equivalent to 

4>[l]i4. 

The dyadic function rotate is also denoted by (J> . If if is a scalar 
or one-element vector and x is a vector, then Ki?X is a cyclic rotation 
of x defined as follows: K$X is equal to z[i+ ( p j) | ~l+K+\pXl . For 
example, if x<-2 3 5 7 11, then 2$X is equal to 5 7 11 2 3 , and ~2$X is 
equal to 7 11 2 3 5. In o-origin indexing, the definition for K$X 
becomes XL (p X) \ K+ ipZ] . 

If the rank of x exceeds 1 , then the coordinate J along which 
roatation is to be performed may be specified by the axis operator in 
the form z-*-K$LJlX. Moreover, the shape of K must equal the remaining 
dimensions of x, and each vector along the Jth axis of x is rotated as 
specified by the corresponding element of K. A scalar K is extended in 
the usual manner. 

For example, if p x is 3 4 and J is 2 , then the shape of K must be 
3 and Z[J;3 is equal to £[J]4>J[I; ] . If J is 1 , then pK must be 4, and 
Z[;J] is equal to X[I]<t>X[ ;T] . For example: 





M 











1 2 3<)>[1]M 




1 2 3C|)[2]W 


1 


2 


3 


4 


1 


6 


11 4 


2 


3 4 1 


5 


6 


7 


8 


5 


10 


3 8 


7 


8 5 6 


9 


10 


11 


12 


9 


2 


7 12 


12 


9 10 11 



The expression K&X denotes rotation along the first axis of x. 

Catenate and Laminate 

Catenate , denoted by a comma, chains vectors (or scalars) together 
to form a vector. For example: 

X+2 3 5 7 11 
X,X 
2357 11 2357 11 

In general, the dimension of x ,Y is equal to the total number of 
elements in x and y. A numeric vector cannot be catenated with a 
character vector. 

The axis operator applies to catenate and determines the axis 
along which vectors are to be catenated. For example; 





M-i-3 


3p 


'ABCDEFGHI< 












M 




M, 


[1]M 


M. 


,[2]M 


M,M 


ABC 






ABC 




ABCABC 




ABCABC 


DEF 






DEF 




DEFDEF 




DEFDEF 


GHI 






GHI 
ABC 
DEF 
GHI 

Section 


3: 


GHIGHI 
Primative 


Funct 


GHIGHI 
ions and Op 



33 



Two arrays are conformable for catenate along axis I if all other 
elements of their shapes agree. Moreover, two arrays may be catenated 
along axis I if they differ in rank by 1 and if the shape of the array 
of lower rank equals the shape of the array of higher rank after 
dropping item I from it. For example: 

V^'PQR' 

M.IX1V M,L21V M.V 

ABC ABCP ABCP 

DEF DEFQ DEFQ 

GHI GHIR GHIR 

PQR 

A scalar argument of catenate will be replicated to form a vector as 
required. For example: 

<7,(C,[1] W.C1] C) ,C 

mm® 

EWBCS 
[SOfi'FS 
BCfflffl 

mmm 

Laminate joins two arrays of identical rank and shape along a new 
axis. The position of the new axis relative to the existing axes is 
indicated by a fractional axis number. For example, if the new axis is 
to be inserted between the existing axes 1 and 2 , the axis number must 
have a value between 1 and 2 . If the new axis is to be inserted ahead 
of the present first axis, the axis number must be between and 1 (or, 
if zero-origin indexing is used, between ~1 and 0). Similarly, if the 
new axis is to be after the last of the present axes, the axis number 
must exceed the index of the present last axis by a fraction between 
and 1 . 

The result of lamination has rank 1 greater than the rank of the 
arguments, and has the same shape except for the interpolation of the 
new axis, along which it has length 2. The comma, which normally 
denotes catenation, followed by an axis operator associated with a 
non-integral index produces lamination. For example: 



5] 217 





W-<-3 


3p 


'ABCDEFGHI' 




2N-3 


3p 


'123456789' 




M 




M,l 


ABC 






ABC 


DEF 






DEF 


GUI 


N 




GHI 


123 






123 


456 






456 


789 






789 





M. 


,[1. 


.5] 217 




M,L2.51N 


ABC 








Al 




123 








B2 
C3 




DEF 












456 








04 
2?5 




GHI 








F6 




789 








Gl 
H8 
J9 





The shapes of the foregoing laminations are 2 3 3 and 3 2 3 and 
3 3 2; the position of the 2 shows the point of new axis insertion in 
each case. 



34 APL Language 



A scalar argument of laminate is extended as required 
example : 



For 



B-<-2 2p'1234' 
B,[2.5]'+' 

1 + 

2 + 

3 + 

4 + 

,B,[2.5]»+» 
1+2+3+4+ 



Transpose 

The expression 2 1W yields the transpose of the matrix M; that 
is, if i?x-2 1§M , then each element R[I;Jl is equal to MM ill. For 
example : ' 





M 








2 ltytf 


1 


2 3 


4 


1 


5 


9 


5 


6 7 


8 


2 


6 


10 


9 


10 11 


12 


3 


7 


11 








4 


8 


12 



If p xs any permutation of the indices of the axes of an array A 
then ptstA is an array similar to A except that the axes are permuted: 
the jth axis becomes the p[T]th axis of the result. Hence, if E<-p<siA , 
then (pi?)[P] is equal to pA . For example: 

A+2 3 5 7pi210 

PA 
2 3 5 7 

P-e-2 3 4 1 

pPM 
7 2 3 5 

More generally, q§a is a valid expression if Q is any vector equal 
in length to the rank of A which is "complete" in the sense that if its 
items include any integer N they also include all positive integers less 
than n. For example, ±f ppA is 3, then 112 and 2 11 and 111 are 
suitable values for q but 1 3 1 is not. Just as for the case P§A where 
P is a permutation, the Jth axis becomes the Q[l]th axis of Q§A. 
However, in this case two or more of the axes of .4 may map into a single 
axis of the result, thus producing a diagonal section of A as 
illustrated below: 



4-e-3 3pl9 S-t-3 5pil5 

A B 

12 3 12 3 4 

4 5 6 6 7 8 9 

7 8 9 11 12 13 14 

1 1§A 1 l(sjB 

15 9 1 7 13 



5 
10 
15 



The monadic transpose ts>A reverses the order of the axes of its 
argument. Formally, ts>A is equivalent to (<t>ippd)*}d. In particular, for 
a matrix a this reduces to 2 1 ^ and is what is commonly called the 
transpose of a matrix. 



Section 3: Primative Functions and Operators 35 



SELECTION FUNCTIONS 

The selection functions are all dyadic; one of the arguments may 
be. an array of any type, and the other, which will be referred to as the 
selector because it serves to specify the selection to be made, must be 
numeric, and, in the case of expand and compress , is further restricted 
to boolean. 

Take a nd Drop 

If s is a non-negative scalar integer and V is a vector, then S + V 
is a vector of dimension s obtained by taking the first S elements of V 
followed (if s>pV) by zeros if v is numeric and by spaces if it is not. 
For example: 

3+2 3 5 7 7 + 2 3 5 7 

235 2357000 

3+MBCDE 1 a+'ABCDE' ) ,*@' 

ABC ABODE @ 

If 5 is a negative integer, then s + V takes elements as above but 
takes the last elements of v and fills as needed on the left. For 
example : 



3+2 3 5 7 



3 5 7 



7+2 3 5 7 
2 3 5 7 



If a is any array, then w+A is valid only if the vector W has one 
element for each axis of a, and will determines what is to be taken 
along the jth axis, of 4. For example: 



A+3 4pil2 

A 
12 3 4 
5 6 7 8 
9 10 11 12 



12 3 
5 6 7 



2 3+4 



"3+4 



2 3 4 
6 7 8 



6 
10 



'2 6+4 



7 
11 



12 



The function drop U) is defined analogously, except that the 
indicated number of elements are dropped rather than taken. For 
example, "1 n-A is the same, matrix as the result of 2 ~3+4 displayed in 
the preceding paragraph. If the number of elements to be dropped along 
any axis equals or exceeds the length of that axis, the resulting shape 
has a zero length for the axis. 

The rank of the result of the take and drop functions is the same 
as the rank of the right argument. 

Compress and Expand 

The expression u/X denotes compression of X by U. If U is a 
boolean vector and x is a vector of the same dimension, then U/X 
produces a vector of +/y elements chosen from those elements of X 
corresponding to non-zero elements of u. For example, if X+2 3 5 7 11 
and u+1 110 then u/X is 2 5 7 and (~U)/X is 3 11. 

C+'THIS IS AN EXAMPLE' 
D+-C*' ' 
Cl+D/C 
CI 
THISISANEXAMPLE 

To be conformable, the dimensions of the arguments must agree, 
except that a scalar argument is extended. Hence l/X is equal to X and 
q/X is an empty vector. 



36 APL Language 



Expansion is the converse of compression and is denoted by u\X . 
If I<-U\X, then u/Y is equal to x and (~y)/j is an array of zeros or 
spaces according as x is numeric or character. In other words, u\X 
expands x to the format indicated by the ones in u and fills in zeros or 
spaces. To be conformable, +/u must equal p x. 

D\C1 
THIS IS AN EXAMPLE 

The axis operator applies to both compress and expand and 
determines the axis along which they apply. If the axis operator is 
omitted, the last axis is used. The symbols / and \ also denote 
compression, but when used without an axis operator apply along the 
first axis. 

Q+3 hp'ABCDEFGHIJKL' 



ABCD 
EFGH 
IJKL 

ABCD 
EFGH 

IJKL 

ABCD 
EFGH 

IJKL 



110 1\[1]< 



1 1 1\( 



BC 
FG 
JK 

ABCD 
IJKL 

ABCD 
IJKL 



Oil 0/<3 



1 1/lllQ 



1 1/Q 



The rank of the result of compress or expand equals the rank of 
the right argument. 

Indexing 

Indexing may be either p- origin or l- origin as discussed in 
Section 2. The following discussion assumes l-origin. If x is a vector 
and I is a scalar, then XLH denotes the jth element of x. For example, 
if X+2 3 5 7 11 then x[2] is 3. 

If the index j is a vector, then xlH is the vector obtained by 
selecting from x the elements indicated by successive components of j. 
For example, xil 3 5] is 2 5 11 and XL 5 4 3 2 l] is n 7 5 3 2. If the 
elements of j do not belong to the set of indices of x, then the 
expression x[r] evokes an index error report. 

In general pXZH equals p j. In particular, if j is a scalar, then 
XLH is a scalar, and if j is a matrix then x[j] is a matrix. For 
example: 

A+-<ABCDEFG' 

I«-4 3p3 1 t 2 1 1 1 1 2 1 1 1 







I 




3 


1 


4 


CAD 


2 


1 


4 


BAD 


4 


1 


2 


DAB 


4 


1 


4 


DAD 



ALII 



If M is a matrix, then m is indexed by a two-part list of the form 
1% J where 1 selects the row (or rows) and j selects the column (or 



Section 3: Primative Functions and Operators 37 



columns) . For example: 

M M[2;3] Mil 3;2 3 4] 

1234 7 234 

5 6 7 8 10 11 12 

9 10 11 12 

In general, pMH;J~\ is equal to (pI),pJ. Hence if J and J are 
both vectors, then Mil; J~\ is a matrix; if both I and J are scalars, 
MiI;J'] is a scalar; if I is a vector and J is a scalar (or vice versa) , 
MiI;J'} is a vector. The indices are not limited to vectors, but may be 
of higher rank. For example, if I is a 3 by 4 matrix, and J is a vector 
of dimension 6, then Mil; J] is of dimension 3 4 6, and MiJ;I~\ is of 
dimension 6 3 4. In particular, if T and P and Q are matrices, and if 



R+TIP 
TlPlI 



], then R is an array of rank 4 and PC J ;J;K;L] is equal to 
iJliQlK-.Ll . 



The form Mil;'] indicates that all columns are selected, and the 
form Mi;J~\ indicates that all rows are selected. For example, Mi 2 ; ] is 
5 6 7 8 and Mi ; 2 1] is the matrix with rows 2 1 and 6 5 and 10 9. 

The following example illustrates the use of a matrix indexing a 
matrix to obtain a three-dimensional array: 

A/f-2 4p 31421441 

M Mi ;M] 

3142 4321 

1441 3223 

4 114 
1111 

An indexed variable may appear to the left of a specification 
arrow if (1) the expression is executable in the environment and (2) 
denoting the values of the expression on the left and right by L and R, 
then l=x/pR or (l*p£)/p£ must equal ( l*pP)/pP. For example: 

X+2 3 5 7 11 
XI 1 3]-*-6 8 
X 
6 3 8 7 11 

SELECTOR GENERATORS 

All of the functions in this group have integer results which, 
although they are commonly useful as the selector argument in selection 
functions, are often used in other ways as well. For example, the grade 
function i is commonly used to produce indices needed to reorder a 
vector into ascending order (as in XiiX]) , but may also be used in the 
treatment of permutations as the inverse function, that is, ^P yields 
the permutation inverse to P. Similarly, \N generates a vector of N 
successive indices, but . lxiff generates a grid of values with an 
interval of . 1 . 

Index Generator and Index of 

The index generator i applies to a non-negative scalar integer N 
to produce a vector of length N containing the first N integers in 
order, beginning with the value of the index origin DIO . For example, 
r5 yields 12 3 4 5 (in 1-origin) or 1 2 3 4 (in 0-origin) , and iO 
yields an empty vector. A one-element vector argument is treated as a 
scalar. 

If V is a vector and S is a scalar, then V\S yields the index (in 

38 APL Language 



the origin in force) of the earliest occurence of s in v, that is, the 
index of S in V. If S differs from all items of v, then V\S yields the 
first index outside the range of V, that is, UlO+pV. 

If S is any array, then V\S yields an array of the shape of s, 
each item being determined as the index in v of the corresponding item 
of S. For example: 



A+'ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 



J+A I ' HEAD 


CHIEF ' 


M«-2 5p' 


J 






M 


8 5 1 4 27 3 8 9 


I 5 


6 


HEAD 


AU1 






CHIEF 


HEAD CHIEF 






A\M 


AlbJl 






8 5 1 4 27 


FEIHC DAEH 






3 8 9 5 6 


A\ 'VAB3 1 








22 1 18 28 








Membership 









HEAD CHIEF' 



The function XeY yields a boolean array of the same shape as x. 
Any particular element of XeY has the value l if the corresponding 
element of x belongs to Y, that is, if it occurs as some element of y. 
For example, (i7)e3 5 is equal to 0010100 and » ABCDEFGH' e' COFFEE' 
equals 00101100. The right argument y may be of any rank. 

The selector argument of compression is commonly provided by 
application of the membership function, alone or in combination with the 
scalar boolean and relational functions. 

Grade Functions 

The grade up function &v grades the items of vector v in ascending 
order, that is, it yields a result of the same dimension as v whose 
first item is the index (in the origin in force) of the smallest item of 
V, whose second item is the index of the next smallest item, and so on. 
Consequently, the expression VlbVl yields the elements of V in ascending 
order. For example, if 7*8 3 7 5, then |Hs 2 t 3 1 and VLiVl is 
3 5 7 8. 

If the items of V are not all distinct, the ranking among any set 
of equal elements is determined by their position. For example, 
A4 3 1 3 4 2 yields 3 6 2 4 15. 

The grade down function yv grades .the items of V in descending 
order; among equal elements the ranking is determined by position just 
as for grade up. Consequently, yv equals the reversal of |7 only if the 
items of V are distinct. For example: 



A+7 2 5 11 3 
iA 
2 5 3 14 

4 13 5 2 



B«-4 3 13 4 2 
iB 
3 6 2 4 15 

15 2 4 6 3 



The grade functions apply only to vectors, 



Deal 



The function M?N produces a vector of length M obtained by making 
M (pseudo-) random selections, without replacement, from the population 



Section 3 : Primative Functions and Operators 



39 



\N. Both arguments are limited to scalars or one-element vectors. Each 
selection is made by appropriate application of the scheme described for 
the function roll . 

The expression N?N yields a random permutation of the items of \N . 
The expression p[A/? p p] selects M distinct elements from the population 
defined by the items of a vector p . For example : 



GBD 



P*-<ABCDEFGH* 
PL3?pP] 



P[(pP)?pP] 
CEADHFGB 



NUMERICAL FUNCTIONS 

The numerical mixed functions apply only to numerical arguments 
and produce numerical results. 

Matrix Inverse and Matrix Divide 

The domino (g) represents two functions which are useful in a 
variety of problems including the solution of systems of linear 
equations, determining the projection of a vector on the subspace 
spanned by the columns of a matrix, and determining the coefficients of 
a polynomial which best fits a set of points in the least-squares sense. 

When applied to a non-singular matrix A the expression SU (matrix 
inverse) yields the inverse of A, and the expression X*-BM (matrix 
divide) yields a value of X which satisfies the relation a/ ,b=A+ .xX and 
is therefore the solution of the system of linear equations 
conventionally represented as Ax=b: 





A+i 


U)« 


. > 


u 














A 








m 






A+, 


. x@/l 


1 









1 








1 








1 1 









1 


1 








1 





1 1 


1 









1 1 








1 





1 1 


1 1 









1 


1 








1 



B<-1 3 6 10 

x+Bm 

B X 

3 6 10 12 3 4 



A+.xX 
1 3 6 10 



(1/1) + . *B 
12 3 4 



Ct-H 2pl 2 3 5 6 9 10 14 



■cm 



10 14 



A+. 

1 2 

3 5 

6 9 

10 14 



xY 



(BA)+.xC 



The final example above shows that if the left argument is a matrix C, 
then c®A yields a solution of the system of equations for each column of 
C 

If A is non-singular and if j is an identity matrix of the same 
dimension, then the matrix inverse SU is equivalent to the matrix divide 
TIE4. More generally, for any matrix p, the expression @P is equivalent 
to the expression ( ( iP) o . = iP)ip, where R is the number of rows in P. 

The domino functions apply more generally to singular and 
non-square matrices, and to vectors and scalars; any argument of rank 
greater than 2 is rejected (RANK ERROR) . For matrix arguments A and B 



HO APL Language 



the expression x+B%A is executed only if 

1. A and B have the same number of rows, and 

2. the columns of A are linearly independent. 

If the _ expression X+BM is executable, then pX is equal to (i + Pi i) i + p b 
and X xs determined so as to minimize the value of the expression' 

+ / AB-A+.xX)*2. 

The domino functions apply to vector and scalar arguments as 
follows: except that the shape of the result is determined as specified 
above, a vector is treated as a one-column matrix and a scalar is 
treated as a one-by-one matrix. The rationale for this interpretation 
of a vector as a one-column (rather than one-row) matrix is that the 
right argument is treated geometrically (as will be seen in a subsequent 
example) as defining a space spanned by its column vectors, and the left 
argument was seen (in an earlier example) to be treated so as to yield a 
solution for each of its column vectors. Indeed, a one-rowed matrix 
right argument (unless 1-by-l) would be rejected under condition 2 
above . 

In the case of scalar arguments X and Y, the expression @J is 
equivalent to *y and, except that it yields a domain error for the case 
0@0, the expression X®Y is equivalent to X*Y . 

The use of H for a singular right argument can be illustrated as 
follows: if x is a vector and Y+F X, then the expression Ym°.*Q,iD 
yields the coefficients of the polynomial of degree D which best fits 
(in the least squares sense) the function F at the points X. 

The definition of BMA has certain useful geometric 
interpretations. If B is a vector and A is a matrix, then saying that 
+ /(.B-A + .*Bm)*2 is a minimum is equivalent to saying that the length of 
the vector B-A+.xBm is a minimum. But A+.xBftA is a point in the space 
spanned by the column vectors of A and is therefore the point in this 
space which is closest to B. In other words, P+A + . xBBA is the 
projection of B on the space spanned by the columns of A. Moreover, the 
vector B-P must be normal to every vector in the space; in particular, 
(B-P)+ .xA is a zero vector. 

If A and B are single-column matrices, then BEA is a l by 1 matrix 

and A+.xBM is equivalent to AxS , where S is the scalar "pBS^. if A 

and B are vectors, then BM is a scalar and the projection of B on A is 
therefore given by the simpler expression AxBm. For example: 



4«-4.5 1.7 

Bf-2 5 

P+AxB%A 

P 
3.403197926 1.28565255 

N+B-P 

N 
1.4-03197926 3.71434745 

N+.xA 
2.442490654£' - 15 



Similar analysis shows that if A is a vector then m is a vector 
in the direction of A; that is, m is equal to SxA for some scalar S. 
Moreover, A+ .x$a is equal to l . In other words, m is the "image" of 



Section 3: Primative Functions and Operators 41 



the vector A obtained by inversion in the unit circle (or sphere) 



Decode and Encode 

For vectors R and X , the decode (or base-value ) function R±X 
yields the value of the vector X evaluated in a number system with 

radices i?[l], RL 2] RtpRl. For example, if B+21 60 60 and x+l 2 3 is 

a vector of elapsed time in hours, minutes, and seconds, then RiX has 
the value 3723, and is the corresponding elapsed time in seconds. 
Similarly, 10 10 10 10 l 1 7 7 6 is equal to 1776, and 222x101 is 
equal to 5. Formally, RiX is equal to + /J/xX, where W is the weighting 
vector determined as follows: WLpWl is equal to 1 and WLJ-ll is equal 
to RLIlxWLIl. For example, if R is 24 60 60, then W is 3600 60 1. 

Scalar (or one-element vector) arguments are treated as usual. 
For example, 10 i 1 7 7 6 yields 1776. The arguments are not restricted 
to integers; for example, if X is a scalar then XiC is the value of the 
polynomial with coefficients C, arranged in descending order on the 
powers of X . 

The decode function is extended to arrays in the manner of the 
inner product operator: each of the radix vectors along the last axis 
of the first argument is applied to each of the vectors along the first 
axis of the second argument. There is one difference; if either of 
these distinguished axes is of length 1 , it will be extended (by 
replication of the element) as necessary to match the length of the 
other argument. Except for this different treatment of unit axes, the 
shape of the result of Ax.B is determined like the shape of the inner 
product, namely (~l + p4) ,1 + pB . 

The encode (or representation ) function RiX is, for certain 
arguments, inverse to the decode function. For example: 

i?«-10 10 10 10 

i?±l 7 7 6 
1776 

i?Tl776 
17 7 6 

More generally, Rl{RjX) equals {*/R)\X rather than X. For example: 

10 10 10 10T123 10 10 10T123 

12 3 12 3 



10 10T123 10T123 



2 3 



More precisely, the definition of the encode function is based on 
the definition of the residue function; for a vector left argument and 
scalar right argument, decode is equivalent to the E whose canonical 
representation is shown at the left below: 



Z+A E B 2 2 2T13 

Z«-0xA 10 1 

I+pA "2 "2 "2T13 

L:-KI=0)/0 1 "1 1 

ZZI1+ALI1\B 2 2T13 

■+U[I] = 0)/0 6 1 

B+(B-ZLI1)*AII1 2 2 2T 13 

I-t-I-1 11 

+£, "2 2 2T13 

11 



42 APL Language 



The basic definition of RtX concerns a vector R and a scalar X , 
and produces a result of the shape of if . It is extended to arrays as 
follows: each radix vector along the first axis of R is applied to 
obtain the representation of each item of X , the resulting 
representations being arrayed along the first axis of the result. For 
example : 

10 10 10T215 4-86 72 219 3 i?+-10 10 10,[1.5]8 8 8 

2 4 2 R 

18 7 10 10 8 

5 6 2 9 3 1Q 8 

10 8 

i?Tl23 

1 1 

2 7 

3 3 

The expression for the shape of the result of RjX is the same as 
for the shape of the outer product, namely ( P R), p x. 

DATA TRANSFORMATIONS 

Of the two functions in this class, the format is a true type 
transformation, being designed to produce a character array which 
represents the data in its numeric argument. Over a certain class of 
arguments the execute function is inverse to the format and is therefore 
considered as a type transformation as well, although its applicability 
is, in fact, much broader. 

Execute and Format 

Any character vector or scalar can be regarded as a representation 
of an APL statement (which may or may not be well-formed) . The monadic 
function denoted by a. takes as its argument a character vector or scalar 
and evaluates or executes the APL statement it represents. When applied 
to a character array that might be construed as a system command or the 
opening of function definition, an error will necessarily result when 
evaluation is attempted, because neither of these is a well- formed APL 
statement. 

The execute function may appear anywhere in a statement, but it 
will successfully evaluate only valid (complete) expressions, and its 
result must be at least syntactically acceptable to its context. Thus, 
execute applied to a vector that is empty, contains only spaces, or 
starts with "-*• (branch symbol) or n (comment symbol) produces no explicit 
result and therefore can be used only on the extreme left. For example: 

4' • 

VALUE ERROR 
Z«-±' ' 

A 

The domain of ± is any character array of rank less than two, and 
RANK and DOMAIN errors are reported in the usual way: 

C«-'3 4' 

+/aC ±3 4 

7 DOMAIN ERROR 

11 3pC 43 4- 

RANK ERROR a 

1 1 3 pC 

A 

Section 3: Primative Functions and Operators 43 



An error can also occur in the attempted execution of the APL 
expression represented by the argument of i ; such an indirect error is 
reported by the error type prefaced by the symbol 4 and followed by the 
character string and the caret marking the point of difficulty. For 
example : 

a. DOMAIN ERROR 
4*0 

A 

1 * ) WSID ' 
4 VALUE ERROR 
)WSID 

A 

The symbol <r denotes two format functions which convert numerical 
arrays to character arrays. There are several significant uses of these 
functions in addition to the obvious one for composing tabular output. 
For example, the use of format is complementary to the use of execute in 
treating bulk input and output, and in the management of combined 
alphabetic and numeric data. 

The monadic format function produces a character array which will 
display identically to the display normally produced by its argument, 
but makes this character array explicitly available. For example: 

M«-2=?4 4p2 

R+lM 

M R 7?[;2xi4] 

0101 0101 0101 

0011 0011 0011 

1011 1011 1011 

0011 0011 0011 

pM pi? 

4 4 4 8 

p<T2 5 Xf-34 

3 X THE VALUE OF X IS ' ,lX 

TEE VALUE OF X IS 34 



1 
ABCD 



A/,i? = Ti? 

▼ MBC7? 1 



The format function applied to a character array yields the 
array unchanged, as illustrated by the last two examples above. For a 
numerical array, the shape of the result is the same as the shape of the 
argument except for the required expansion along the last coordinate, 
each number going, in general, to several characters. The format of a 
scalar number is always a vector. 

The printing normally produced by APL systems may vary slightly 
from system to system, but the result produced by the monadic format 
will have no final column of all spaces, and no initial spaces in the 
case of a vector or scalar argument. 

The dyadic format function accepts only numerical arrays as its 
right argument, and uses variations in the left argument to provide 
progressively more detailed control over the result. Thus, for EvA , the 
argument F may be a single number, a pair of numbers, or a vector of 
length 2x~l-M,p J 4. 

In general, a pair of numbers is used to control the result: the 
first determines the total width of a number field, and the second sets 
the precision . For decimal form the precision is specified as the 

HH APL Language 



number of digits to the right of the decimal point, and for scaled form 
it is specified as the number of digits in the multiplier. The form to 
be used is determined by the sign of the precision indicator, negative 
numbers indicating scaled form. Thus: negative 



3 2 



pO+A 
12 . 34 
_0 
0.26 

i?«-9 2fA 
S+9 ~2<fA 



34.567 
12 
"123. 45 



3 24 



pD«-12 3fA 

12.340 "34.567 
.000 12.000 
.260 "123.450 



12.34 
_.00 
.26 
3 18 

pQf-5 
1.2501 
_0 .0500 
2.65 01 
3 18 



34.57 

12 .00 

"123. 45 



5501 
2501 
2502 



pD*-6 Of A 
12 "35 
12 
123 
3 12 

pD«-7 ~1*A 
1501 ~3EQ1 
0E00 1E01 

~35~01 ~±E02 
3 14 



If the width indicator of the control pair is zero, a field width 
is chosen such that at least one space will be left between adjacent 
numbers. If only a single control number is used, it is treated like a 
number pair with a width indicator of zero: 



p0-*-2vA 
12.34 "34.57 
_.00 12.00 

.26 "123.45 
3 16 

pQ-f-0 2vA 
12.34 "34.57 
.00 12.00 

".26 "123.45 
3 16 



pD+-~2<M 
1.2501 "3.5501 
0.050 1.2501 

~2.65~01 "1.2502 
3 18 

pCH-0 ~2VA 
1.2501 ~3. 5E01 
0.0500 1.2501 

~2.65 01 "1.2502 
3 18 



Each column of an array can be individually composed by a left 
argument that has a control pair for each: 



pD«-0 2 2wA 
12.34 "34.57 
.00 12.00 

".26 "123.45 
3 15 

pQ-<-6 2 12 ~3Ti4 
12.34 "3.46S01 

.00 1.20501 

".26 "1.23502 

3 18 



pQ«-8_3 2JA 
12.340 34.57 
.000 12.00 
".260 "123.45 
3 16 

pQf-8 ~2Ti4 
12 "3.5501 
1.2501 
"1.2502 
3 17 



6283304050 12 4t ,A 
12.34 34.567 12 "123.4500 



The format function applied to an array of rank greater than two 
applies to each of the planes defined by the last two axes. For 
example : 



Section 3: Primative Functions and Operators 



45 



L«-2 = ?2 2 5p2 

L 4 1TL 

110 1 1.01.0 0.00.01.0 

1110 1 i.o 1-0 1 -° °-° 1 -° 

10 10 1.00.00.01.00.0 

ooooo 0.00.00.00.00.0 

Tabular displays incorporating row and column headings, or other 
information between columns or rows, are easily configured using the 
format function together with catenation. For example: 

ROWHEADS*-k Zq'JANAPRJULOCT' 

YEARS+71-HS 

TABLE*-. 001x~4£5+?4 5p8£5 

(• » ,il^ROWHEADS), (.2^9 OvYEARS) , [ 1 ] 9 If TABLE 

72 73 7 4 75 _76 

JAN 318.13 "351.55 _ 3.62 "144.77 4.82 

APR "327.41 "341.00 "92.69 331.05 28.44 

JUL "359.93 216.16 _299..71 150.77 103.64 

OCT 180.33 310.86 154.94 10.62 276.79 

There are obvious restrictions on the left argument of format, 
since the width of a field must be large enough to hold the requested 
form, and if the specified width is inadequate the result will be a 
DOMAIN error. However, the width need not provide open spaces between 
adjacent numbers. For example, boolean arrays can be tightly packed: 

1 0?2=?4 4p2 
1001 
0000 
1101 
0111 

The following formal characteristics of the format function need 
not concern the general user, but may be of interest in certain 
applications : 

The least width needed for a column of numbers C with precision P is 
RMv/f?<o) + (~PeO ~l) + ( |P) + (4,("/0,(i?*0) + L10®|i?+i?=0)[l+P2:0], where S is 
the rounded value of C given by i?«-(L . 5 + C*io* I P)*10* I P. 

The expressions (MvA) ,N*B and (M,N)vA,B are equivalent if M and N 
are full control vectors, that is, if ( ( P A/)=2x"l+ P A ) A(ptf)=2x 1+pB. 
If 2 = pA7, then (MjA) ,MjB and MvA.B are equivalent. 



46 APL Language 



SECTION 4 : SYSTEM FUNCTIONS AND SYSTEM VARIABLES 

Although the primitive functions of APL deal only with abstract 
objects (arrays of numbers and characters), it is often desirable to 
bring the power of the language to bear on the management of the 
concrete resources or the environment of the system in which APL 
operates. This can be done within the language by identifying certain 
variables as elements of the interface between APL and its host system, 
and using these variables for communication between them. While still 
abstract objects to APL, the values of such system variables may have 
any required concrete significance to the host system. 

In principle all necessary interaction between APL and its 
environment could be managed by use of a complete set of system 
variables, but there are situations where it is more convenient, or 
otherwise more desirable, to use functions based on the use of system 
variables which may not themselves be made explicitly available. Such 
functions are called, by analogy, system functions . 

System variables and system functions are denoted by distinguished 
names that begin with a quad (Q) . The use of such names is reserved for 
the system and cannot be applied to user-defined objects. They cannot 
be copied, grouped, or erased; those that denote system variables can 
appear in function headers, but only to be localized (see Section 6) . 
Within APL statements, distinguished names are subject to all the normal 
rules of syntax. 

SYSTEM FUNCTIONS 

Like the primitive abstract functions of APL, the system functions 
are available throughout the system, and can be used in defined 
functions. They are monadic or dyadic, as appropriate, and have 
explicit results. In most cases they also have implicit results, in 
that their execution causes a change in the environment. The explicit 
result always indicates the status of the environment relevant to the 
possible implicit result. 

Altogether, 13 system functions are provided. Six of these are 
concerned with the management of the shared-variable facility and are 
described in Section 5. The other seven are given in Figure 4.1, and 
are described here. 

CANONICAL REPRESENTATION 

The canonical representation of a defined function as defined in 
Section 6 is obtained as a result of applying the system function OCR to 
the character array representing the name of the function. Applied to 
any argument which does not represent the name of an unlocked defined 
function it yields a matrix of dimension o by o. Possible error reports 
for OCR are 'RANK error if the argument is not a vector or a scalar, or 
DOMAIN error if the argument is not a character array. The use of OCR 
is further described in Section 6. 

FUNCTION ESTABLISHMENT 

The definition of a function can be established or fixed by 
applying the system function OFX to its character representation. The 
function OFX produces as an explicit result the array of characters 
which represents the name of the function being fixed, while replacing 
any existing definition of a function with the same name. 



Section 4: System Functions and System Variables 47 



FUNCTION 



UCR A 



UFX M 



OEX A 



DNL N 



REQUIREMENTS 



RANK LENGTH 



l>pp4 



2 = ppM 



2>ppA 



l>ppff 



A DNL N 



DNC A 



DDL S 



lappiV 



2£ppM 



lappS 



lip. 5 



DOMAIN 

Array of 
characters. 



Matrix of 
characters. 



Array of 
characters. 



A/Nel 2 3 



A/flel 2 3 
Elements of 
A must be 
alphabetic. 

Array of 
characters. 



EFFECT ON ENVIRONMENT 



None. 



Fix (establish) definition of 
the function represented by M, 
unless its name is already in 
use for an object other than 
function which is not halted. 

Expunge (erase) objects named 
by rows of A, except groups, 
labels, or halted functions. 

None. 



None. 



None. 



Numeric 
value. 



None, but requires S seconds 
to complete. 



EXPLICIT RESULT 

Canonical representation of 
object named by A. The re- 
sult for anything other than 
an unlocked defined function 
is of size 0. 

A vector representing the 
name of the function estab- 
lished, or the scalar row 
index of the fault which 
prevented establishment. 

A boolean vector whose Ith 
element is 1 if the Ith name 
is now free. 

A matrix of rows (in acci- 
dental order) representing 
names of designated kinds in 
the dynamic environment: 
1, 2, 3 for labels, varia- 
bles, functions. 

As for the monadic form, 
except that only names be- 
ginning with letters in A 
will be included. 

A vector giving the usage of 
the name in each row of A : 

name is available 

1 label 

2 variable 

3 function 

4 other 

Scalar value of actual 
delay. 



Figure 4.1: System Functions 

An expression of the form DFX M will establish a function if both the 
following conditions are met: 

1. M is a valid representation of a function. Any matrix which 
differs from a canonical matrix only in the addition of 
non- significant spaces (other than rows consisting of spaces 
only) is a valid representation. 

2. The name of the function to be established does not conflict 
with an existing' use of the name for a halted function (defined 
in Section 7) or for a label, group, or variable. 

If the expression fails to establish a function then no change occurs in 
the workspace and the expression returns a scalar index of the row in 
the matrix argument where the fault was found. If the argument of UFX 
is not a matrix a RANK error will be reported, and if it is not a 
character array a DOMAIN error will result. 

EXPUNGE 

Certain name conflicts can be avoided by using the expunge 
function OEX to dynamically eliminate an existing use of a name. Thus 
OEX •Pejf?' will erase the object PQR unless it is a label, a group, or a 



48 APL Language 



halted function. The function returns an explicit result of l if the 
name is now unencumbered, and a result of o if it is not, or if the 
argument does not represent a well- formed name. The expunge function 
applies to a matrix of names and then produces a logical vector result. 
QEX will report a RANK error if its argument is of higher rank than a 
matrix, or a DOMAIN error if the argument is not a character array. A 
single name may also be presented as a vector or scalar. 

NAME LIST 

The dyadic function QNL yields a character matrix, each row of 
which represents the name of an object in the dynamic environment. The 
right argument is an integer scalar or vector which determines the class 
of names produced as follows: 1, 2, and 3 respectively invoke the names 
of labels, variables, and functions. The left argument is a scalar or 
vector of alphabetic characters which restricts the names produced to 
those with an initial letter occurring in the argument. The ordering of 
the rows of the result is fortuitous . 

The monadic function QNL behaves analogously with no restriction 
on initial letters. For example, QNL 2 produces a matrix of all 
variable names, and either of QNL 2 3 or QNL 3 2 produces a matrix of 
all variable and function names. 

The uses of 'QNL include the following: 

In conjunction with QEX, all the objects of a certain class can 
be dynamically erased; or a function can be readily defined that 
will clear a workspace of all but a preselected set of objects. 

In conjunction with QCR , functions can be written to 
automatically display the definitions of all or certain 
functions in the workspace, or to analyze the interactions among 
functions and variables. 

The dyadic form of QNL can be used as a convenient guide in the 
choice of names while designing or experimenting with a 
workspace. 

NAME CLASSIFICATION 

The monadic function QNC accepts a matrix of characters and 
returns a numerical indication of the class of the name represented by 
each row of the argument. A single name may also be presented as a 
vector or scalar. 

The result of QNL is a suitable argument for QNC, but other 
character arrays may also be used, in which case the possible results 
are integers ranging from to 4. The significance of l, 2, and 3 are 
as for QNL} a result of signifies that the corresponding name is 
available for any use; a result of u signifies that the argument is not 
available for use as a name. The latter case may arise because the name 
is in use for denoting a group, or because the argument is a 
distinguished name or not a valid name at all. 

DELAY 

The delay function, denoted by QDL , evokes a pause in the 
execution of the statement in which it appears. The argument of the 
function determines the duration of the pause, in seconds, but the 
accuracy is limited by possible contending demands on the system at the 
moment of release. Moreover, the delay can be aborted by a strong 

Section 4: System Functions and System Variables 49 



interrupt. The explicit result of the delay function is a scalar value 
equal to the actual delay. If the argument of DDL is not a scalar with 
a numerical value, a RANK or DOMAIN error will be reported. 

Generally speaking, the delay function uses only a negligible 
amount of computer time (as opposed to connect time) . It can therefore 
be used freely in situations where repeated tests may be required at 
intervals to determine whether an expected event has taken place. This 
is useful in work with shared variables (as in the function OFFER given 
as an example in Section 5) , as well as in certain kinds of interactions 
between users and programs. 

SYSTEM VARIABLES 

System variables are instances of shared variables , which are 
treated in Section 5. The characteristics of shared variables that are 
most significant here are these: 

1. If a variable is shared between two processors, the value of the 
variable when used by "one of them may well be different from 
what that processor last specified, and 

2. each processor is free to use or not use a value specified by 
the other, according to its own internal workings. 

System variables are shared between a workspace and the APL 
processor. Sharing takes place automatically each time a workspace is 
activated and, when a system variable is localized in a function, each 
time the function is used. 

The system variables are listed in Figure 4.2, which gives their 
significance and use. Two classes can be discerned: 

1. Comparison tolerance, index origin, latent expression, random 
link, printing precision, and printing width. In these cases 
the value specified by the user (or available in a clear 
workspace) is used by the APL processor during the execution of 
operations to which they relate. If this value is 
inappropriate, or if no value has been specified after 
localization, an IMPLICIT error will be evoked at the time of 
execution. 

2. Account information, atomic vector, line counter, time stamp, 
terminal type, user load, and work area. In these cases 
localization or setting by the user are immaterial. The APL 
processor will always reset the variable before it can be used 
again. 

The APL statement represented by the latent expression is 
automatically executed whenever the workspace is activated. Formally, 
DLX is used as an argument to the execute function (*QLX) , and any error 
message will be appropriate to the use of that function. 

Common uses of the latent expression include the form QLX+'G* used 
to invoke an arbitrary function G, the form: 

QLX+ " ' FOR NEW FEATURES IN THIS WS ENTER: NEW" 

used to print a message upon activation of the workspace, and the form 
DLX-*- , -*ULC t used to automatically restart a suspended function. The 
variable DLX may also be localized within a function and respecified 
therein to furnish a different latent expression when the function is 



50 APL Language 



NAME 


PURPOSE 


VALUE IN 
CLEAR WS 


MEANINGFUL 
RANGE 


uct 


Comparison tolerance: used in monadic f L, dyadic << = £>*£ i 


1£~13 


0-1 


DIO 


Index origin: used in indexing and in ? i i H QP-^ 


1 


1 


ULX 


Latent expression executed on activation of workspace 


i t 


characters 


DPP 


Printing precision: affects numeric output and monadic v 


10 


116 


Upw 


Printing width: affects all but bare output and error reports 


(system dependent) 


URL 


Random link: used in ? 


7*5 


i. 1 + 2*31 


OAI 


Account information: identification, computer time, connect 
time, keying time (all times in milliseconds and cumulative 
during session) 






UAV 


Atomic vector 






ULC 


Line counter: statement numbers of functions in execution or 
halted, most recently activated first 


\0 




UTS 


Time stamp: year, month, day (of month) , hour (on 24-hour 
clock), minute, second, millisecond 






DTT 


Terminal type: 1 for Selectric, 2 for PTTC/BCD, 3 for 1050 






UUL 


User Load 






UWA 


Working area available (in bytes) 







Figure 4.2: System Variables 



suspended. 



[13 
[2] 
[3] 



For example : 

QLX+ ' F • 

V F;ULX 

ULX*-'+ULC,pU<r"WE CONTINUE FROM WHERE WE LEFT OFF'" 

'WE NOW BEGIN LESSON 2' 

DRILLFUNCTION V 

)SAVE ABC 



On the first activation of workspace ABC, the function F would be 
automatically invoked; if it were later saved with F halted, subsequent 
activation of the workspace would automatically continue execution from 
the point of interruption. 

The atomic vector UAV is a 256-element character vector, 
containing all possible characters. Certain elements of UAV may be 
terminal control characters, such as carrier return or linefeed, but 
other elements of UAV may neither print nor exercise control. The 
indices of any known characters can be determined by an expression such 
as UAVx >ABCABC X . 



Section 4: System Functions and System Variables 51 



SECTION 5: SHARED VARIABLES 

Two otherwise independent concurrently operating processors can 
communicate , and thereby be made to cooperate, if they share one or more 
variables. Such shared variables constitute an interface between the 
processors, through which information may be passed to be used by each 
for its own purposes. In particular, variables may be shared between 
two active APL workspaces, or between an APL workspace and some other 
processor that is part of the overall APL system, to achieve a variety 
of effects including the control and utilization of devices such as 
printers, card readers, magnetic tape units, and magnetic disk storage 
units. 

In use in an APL workspace, a shared variable may be either global 
or local, and is syntactically indistinguishable from ordinary 
variables. It may appear to the left of an assignment, in which case 
its value is said to be set , or elsewhere in a statement, where its 
value is said to be used . Either form of reference is an access . 

At any instant a shared variable has only one value, that last 
assigned to it by one of its owners. Characteristically, however, a 
processor using a shared variable will find its value different from 
what it might have set earlier. 

A given processor can simultaneously share variables with any 
number of other processors. However, each sharing is bilateral; that 
is, each shared variable has only two owners. This restriction does not 
represent a loss of generality in the systems that can be constructed, 
and commonly useful arrangements are easily designed. For example, a 
shared file can be made directly accessible to a single control 
processor which communicates bilaterally with (or is integral with) the 
file processor itself. In turn, the central processor shares variables 
bilaterally with each of the using processors, controlling their 
individual access to the data, as required. 

It was noted in Section 4 that system variables are instances of 
shared variables in which the sharing is automatic. It was not pointed 
out, however, that access sequence disciplines are also imposed on 
certain of these variables, although one effect of this was noted; 
namely, variables like the time stamp accept any value specified, but 
continue to provide the proper information when used. The discipline 
that accomplishes this effect is an inhibition against two successive 
accesses to the variable unless the sharing processor (the system) has 
set it in the interim. 

When ordinary, "undistinguished", variables are to be shared, 
explicit actions are necessary to effect the sharing and establish a 
desired access discipline. six system functions are provided for these 
purposes: three for the actual management and three to provide related 
information. These are summarized in Figure 5.1. 

OFFERS 

A single offer to share is of the form p USVO N, where p is the 
identification of another processor and N is a character vector 
representing a pair of names. The first of this pair is the name of the 
variable to be shared, and the second is a surrogate name which is 
offered to match a name offered by the other processor. The name of the 
variable may be its own surrogate, in which case only the one name need 
be used, rather than two. For example, the three sets of actions shown 
below all have the same effect, which is to share one variable between 
two processors 12 34 and 567 8, the variable being known to the former as 

52 APL Language 



FUNCTION 


REQUIREMENTS [1] 


EFFECT ON ENVIRONMENT 


EXPLICIT RESULT 


RANK 


LENGTH 


DOMAIN 


P'QSVO N 


22ppff 


(x/pP)el ,~l+pff 


Pe~l+i2*31 

[2] 


Tenders offer to processor 
P if first (or only) name 
of a pair is not previously 
offered and not already in 
use as the name of an ob- 
ject other than a variable. 
The offer is general (to 
anyone) if 0=P. 


Degree of coupling now in 
effect for the name pair. 
Dimension: x/ 1+pff. 


DSVO N 


2!>ppff 


None. 


[2] 


None. 


Degree of coupling now in 
effect for the name pair. 
Dimension: x/~i+pff. 


C OSVC N 


2>ppff 
2>ppC 


(l>ppC) Al=x/pC 

or 

(pC) = ( l + pJV),4 


A/CeO 1 
[2] 


Sets access control. 


New setting of access con- 
trol. 
Dimension: ( l+pff),4. 


QSVC N 


2!>ppff 


None. 


[2] 




Existing access control. 


USVR N 


2>ppff 


None. 


[2] 


Retracts offer (ends shar- 
ing) . 


Degree of coupling before 
this retraction. 
Dimension: x/'UpN. 


QSVQ P 


l>ppP 


1*P,P 


Pe - l+i2*31 


None. 


If 0=pP: Vector of identi- 
fications of processors 
making offers to this 
user. 

If l=x/pP: Matrix of names 
offered by processor P 
but not yet shared. 



NOTES: 1. If a requirement is not met the function is not executed and a corresponding error 
report is printed. 
2. Each row of N (or N itself if 22ppff) must represent a name or pair of names. If a 
pair of names is used for an offer (dyadic DSVO), either the pair, or the first 
name only, can be used for the other functions. 

Figure 5.1; Functions for the Management of Sharing 

ABC, and to the latter as Q. 

User 12 34 User 5 67 8 

5678 QSVO 'ABC Y« 
1 1234 DSVO 'Q Y' 



5678 DSVO 'ABC Q* 



1234 DSVO •«' 



5678 DSVO MAC 1 



12 34 DSVO iQ ABC 1 



The surrogate names have no effect other than to control the 
matching, making it possible for one processor to operate with no direct 
knowledge of, or concern with, the variable name used by the other. The 
same surrogate can be used in a succession of offers to the same 
processor, in which case they are matched in sequence by appropriate 
counter-offers. The same surrogate may also be used for offers to any 
number of other processors at the same time. However, since a variable 
may be offered to (or shared with) only one other processor at a time, 
each coincident use of a particular surrogate name must be associated 
with a different variable name. 



Section 5: Shared Variables 



53 



The explicit result of the expression P DSVO N is the degree of 
coupling of the name or name pair in N: zero if no offer has been made, 
one if an offer has been made but not matched, two if sharing is 
completed. An offer to any processor (other than the offering processor 
itself) increases the coupling of the name offered if the name has zero 
coupling and is not the name of a label, function, or group. An offer 
never decreases the coupling. 

The monadic function DSVO does not affect the coupling of the name 
represented by its argument, but does report the degree of coupling as 
its explicit result. If the degree of coupling is one or two, a 
repeated offer has no further implicit result and either monadic or 
dyadic DSVO may be used for inquiry. Advantage is taken of this in the 
following example of a defined function for offering a name (to be 
entered on request) to a processor P for a period of T seconds: 

Z+P OFFER T;I;Q 
m«- ' NAME : ' 

■+( • <K.=Q+a)/z+-i*-o 

Il:-v(2 = Zf-P DSVO Q)/L2 

■+(TzI+I+l + OxDDL 1)/L1 

'NO DEAL* 

+ 

L2: 'ACCEPTED' V 

If the arguments of DSVO fail to meet any of the basic 
requirements listed in Figure 5.1, the appropriate error report is 
evoked and the function is not executed. If a user attempts to share 
more variables than the quota allotted to him by those responsible for 
the general management of the system the error report will be INTERFACE 
QUOTA EXHAUSTED, and if, for any reason, the shared variable facility 
itself is not available the report will be NO SHARES. An offer to a 
processor will be tendered, whether or not the processor happens to be 
available. 

The value of a shared variable when sharing is first completed is 
determined thus: if both owners had assigned values beforehand, the 
value is that assigned by the first to have offered; if only one owner 
had, that value obtains; if neither had, the variable has no value. 
Names used in sharing are subject to the usual rules of localization. 

A set of offers can be made by using a vector left argument (or a 
scalar or one-element vector which is automatically extended) and a 
matrix right argument, each of whose rows represents a name or name 
pair. The offers are then treated in sequence and the explicit result 
is the vector of the resulting degrees of coupling. If the quota of 
shared variables is exhausted in the course of such a multiple offer, 
none of the offers will be tendered. 

An offer made with zero as left argument is a general offer, that 
is, an offer to any processor. A general offer will be matched only 
with a counter-offer which is not general, that is, one that explicitly 
identifies the processor making the general offer. The processor 
identification associated with a user is the user's, sign-on number. 
Auxiliary processors are usually identified by numbers between 1 and 
1000. 



54 APL Language 



ACCESS CONTROL 

Consider the following simple example of sharing the variable 7 
between two users 1234- and 567 8: 



User 1234 



User 5 67 8 



5678 QSVO '7* 

V+-5 
V 



123"+ QSVO '7' 



7-*-3x7*2 



75 



The relative sequence of events in the two workspaces, after sharing, is 
significant; for example, had the use of 7 by 1234 in the foregoing 
example preceded the setting by 567 8, the resulting value would have 
been 5 rather than 7 5 . 

In most practical applications it is important to know that a new 

value has been assigned between successive uses of a shared variable, or 

that use has been made of an assigned value before a new one 'is set. 

Since, as a practical matter, this cannot be left to chance, an access 

control mechanism is embodied in the shared variable facility. 

The access control operates by inhibiting the setting or use of a 
shared variable by one owner or the other, depending upon the access 
state of the variable, and the value of an access control matrix which 
is set jointly by the two owners, using the dyadic form of the system 
function QSVC . If, in the example above, one user (say 567 8) had 
followed his offer to share 7 by the expression l l l 1 QSVC '7', then 
the desired sequence would have been enforced. That is, the use of 7 by 
5678 would be automatically delayed until 7 is set by 1234, and the use 
by 1234 would be delayed until 7 is set by 5678. 

The delay occasioned by the inhibition of any access uses only a 
negligible amount of computer time. Interruption by a strong interrupt 
signal during the period of delay aborts the access and unlocks the 
keyboard . 



Figure 5.2 shows 
variable, the possible 
inhibitions imposed by 
ACM is associated with 
second with its use. 
indicated by the zeros 
the access state shown 
Figure 5.2 to validate 



the three access states possible for a shared 
transitions between states, and the potential 
the access control matrix, ACM. The first row of 
setting of the variable by each owner, and the 
The permissible operations for any state are 
in ACMaasm, where ASM is the representation of 
in the figure. This can be confirmed by using 
each of the following statements : 



If ACMLl -,l] = l r then two successive sets by A require an intervening 
access (set or use) by B. 

If ACMll;2l=l, then two successive sets by B require an intervening 
access by A. 

If ACMi2;ll=li then two successive uses by A require an intervening 
set by B. 

If ACML2;2l=l, then two successive uses by B require an intervening 
set by A. 

The value of the access state representation is not directly 
available to a user, but the value of the access control matrix is given 
by the monadic function QSVC. For a shared variable 7 the result of the 



Section 5: Shared Variables 



55 




Legend : 

SA SB UA UB 



Denote set or use by A 
ACM: Access Control Matrix 
ASM: Access State Matrix 



or B. 



A one in an element of ACM inhibits the 
associated access. Allowable accesses are 
given by the zeroes in ACM^ASM. Access control 
vectors as seen by A and B, respectively, are 

,ACM and AACM. 

The access state matrix represents the last 
access : ones occur in the last row if it is not 
a set, and in a column if it is, the first 
column if set by A and the last if set by B. 



Figure 5.2: Access Control of a Shared Variable 



56 APL Language 



Access Control Vector 
as seen by 


Comments 


A 


B 


No constraints. 

Half -duplex. Ensures that each use is 
preceded by a set by partner. 

Half-duplex. Ensures that each set is 
preceded by an access by partner. 

Reversing half-duplex. Maximum 
constraint. 

Simplex. Controlled communication from 
B to A. (For card reader, etc.) 



11 

110 

1111 

110 



11 

110 

1111 

10 1 



Figure 5.3: Some Useful Settings for the Access Control Vector 



expression USVC '7' executed by user A is the access control vector ,ACM 
(the four-element ravel of ACM). However, if user B executed the same 
expression he would obtain the result ,<$>ACM. The reason for the 
reversal is that sharing is symmetric: neither owner has precedence 
over the other, and each sees a control vector in which the first one of 
each pair of control settings applies to his own accesses. This 
symmetry is evident in Figure 5.2; if it were redrawn to interchange the 
roles of A and B the control matrix would be the row-reversal of the 
matrix shown. 

The setting of the access control matrix for a shared variable is 
determined in a manner which maintains the functional symmetry. An 
expression of the form L USVC 'V executed by user A assigns the value 
of the logical left argument L to a four-element vector which, for the 
purposes of the present discussion, will be called QA. Similar action 
by user B sets QB . The value of the access control matrix is determined 
as follows: 

ACM*-(2 2pQA)v§2 2pQB 

Since ones in ACM inhibit the corresponding actions, it is clear from 
this expression that one -user can only increase the degree of control 
imposed by the other (although he can, by using USVC with a left 
argument of zeros, restore the control to that minimum level at any 
time) . 

Access control can be imposed only after a variable is offered, 
either before or after the degree of coupling reaches two. The initial 
values of QA and QB when sharing is first offered are zero. 

The access state when a variable is first offered (degree of 
coupling is one) is always the initial state shown in Figure 5.2. If 
the variable is set or used before the offer is accepted, the state 
changes accordingly. Completion of sharing does not change the access 
state. 



Figure 5.3 lists a number of settings of the access control vector 
which are of common practical interest. Any one of them can be 
represented by a simplification of Figure 5.2 obtained by omitting the 
control matrix and deleting the lines representing those accesses which 
are inhibited in the particular case. For example, with maximum 
constraints all the inner paths would be removed from the figure. 



Section 5 : Shared Variables 



57 



A group of N access control matrices can be set at once by 
applying the function OSVC to an if by t matrix left argument and an 
tf-rowed matrix right argument of names. The explicit result is an N by 
u- matrix giving the current values of the (ravels of) control matrices. 
When control is being set for a single variable the left argument may be 
a single 1 or. if all inhibits or none are intended. 

RETRACTION 

Sharing offers can be retracted by the monadic function DSVR 
applied to a name or a matrix of names. The explicit result is the 
degree (or degrees) of coupling prior to the retraction. The implicit 
result is to reduce the degree of coupling to zero. 

Retraction of sharing is automatic if the connection to the 
computer is interrupted or if the user signs off or loads a new 
workspace. Sharing of a variable is also retracted by its erasure or, 
if it is a local variable, upon completion of the function in which it 
appeared. 

The nature of the shared-variable implementation is often such 
that the current value of a variable set by a partner will not be 
represented within a user's workspace until actually required to be 
there. This requirement obtains when the variable is to be "used, when 
sharing is terminated, or when a SAVE command is issued (since the 
current value of the variable must be stored) . Under any of these 
conditions it is possible for a WS FULL error to be reported. In all 
cases the prior access state remains in effect and the operation can be 
retried after corrective action. 

INQUIRIES 

There are three monadic inquiry functions which produce 
information concerning the shared variable environment but do not alter 
it; the functions QSVOand USVC already discussed, and the function OSVQ. 
A user who applies the latter function to an empty vector obtains a 
vector result containing the identification of each user making any 
sharing offer to him. A user who applies the function OSVQ to a 
non-empty argument obtains a matrix of the names offered to him by the 
processor identified in the argument. This matrix includes only those 
names which have not been accepted by counter-offers. 

The expression (.Q*OSVO AO/Cl] M+ONL 2 can be used to produce a 
character matrix whose rows represent the names of all shared variables 
in the dynamic environment. 



58 APL Language 



SECTION 6: FUNCTION DEFINITION 

There are three ways in which a defined function can be 
established in an APL workspace: 

1. It can be copied from a stored workspace using a system command, 
as described in Section 8. 

2. It can be established in execution mode, using the system 
function DFX, either in direct keyboard entry or in the course 
of execution of another defined function. 

3. It can be established in function definition mode. 

Regardless of which facility has been used for establishing a function, 
its definition can be displayed or modified in either the function 
definition mode, in which certain editing capabilities are built-in, or 
by the combined use of the system functions OCR and QFX. 

CANONICAL REPRESENTATION AND FUNCTION ESTABLISHMENT 

The character representation of a function is a character matrix 
satisfying certain constraints: the first row of the matrix represents 
the function header and must be one of the forms specified below in the 
section on function headers. The remaining rows of the matrix, if any, 
constitute the function body , and may comprise any sequence of 
characters. If the character representation satisfies additional 
constraints such as no redundant spaces and left justification of the 
non-blank character in each row, then it is said to be a canonical 
representation . 

Applying OCR to the character array representing the name of an 
already established function will produce its canonical representation. 
For example, if OVERTIME is an available function: 

DEF+OCR 'OVERTIME* 

DEF 
PAI+R OVERTIME H;TIME 
TIME+0\H-H0 
PAY+R*1.5xTIME 

pDEF 
3 21 

The function QCR applied to any argument which does not represent the 
name of an unlocked defined function yields a matrix of shape 0. 
Error reports for QCR are RANK error if the argument is not a vector or 
a scalar, or DOMAIN error if the argument is not a character array. 

The use of OCR does not change the status of the function 
OVERTIME, which remains established and can be used for calculations. 
Thus: 

7 5 8 OVERTIME 3 5 40 4-5 
60 

If OVERTIME should be expunged: 

DEX 'OVERTIME* 



Section 6 : Function Definition 59 



it is no longer available for use : 

7 5 8 OVERTIME 3 5 40 45 
SYNTAX ERROR 

7 5 8 OVERTIME 3 5 40 4 5 
A 

The function can be re-established by UFXi 

QFX DEF 
OVERTIME 

The function QFX produces as its explicit result the vector of 
characters which represents the name of the function being fixed, while 
replacing any existing definition of a function with the same name. The 
function OVERTIME can now be used again: 

7 5 8 OVERTIME 3 5 40 4 5 
60 

As noted in Section 4, an expression of the form UFX M will 
establish a function if the following conditions are met: 

1. M is a valid representation of a function. Any matrix which 
differs from a canonical matrix only in the addition of 
non-significant spaces (other than rows consisting of spaces only) 
is a valid representation. 

2. The name of the function to be established does not conflict with 
an existing use of the name for an executing or halted function or 
for a label, group, or variable. 

If the expression fails to establish a function then no change occurs in 
the workspace and the expression returns a scalar index of the row in 
the matrix argument where the fault was found. If the argument of DFX 
is not a matrix a RANK error will be reported, and if it is not a 
character array a DOMAIN error will result. 

THE FUNCTION HEADER 

The v alence of a function is defined as the number of explicit 
arguments which it takes. A defined function may have a valence of 
zero, one, or two, and may yield an explicit result or not. These cases 
are represented by six forms of header as follows: 

Type Valence Result No Result 

Dyadic 2 R+-A F B A F B 

Monadic i r+f B F B 

Niladic R+F F 

The names used for the arguments of a function become local to the 
function, and additional local names may be designated by listing them 
after the function name and argument, separated from them and from each 
other by semicolons; the name of the function is global . The 
significance of these distinctions is explained below. 

Except that the function name itself may be repeated in the list 
of local names, a name may not be repeated in the header. It is not 
obligatory either for the arguments of a defined function to be used 
within the body, or for the result variable to be specified in the 
course of function execution. 



60 APL Language 



LOCAL AND GLOBAL NAMES 

In the execution of a defined function it is often necessary to 
work with intermediate results or temporary functions which have no 
significance either before or after the function is used. The use of 
local names for these purposes, so designated by their appearance in the 
function header, avoids cluttering the workspace with a multitude of 
objects introduced for such transient purposes, and allows greater 
freedom in the choice of names. Names used in the function body, and 
not so designated, are said to be global to that function. 

A local name may be the same as that for a global object, and any 
number of names local to different functions may be the same. During 
the execution of a defined function, a local name will temporarily 
exclude from use a global object of the same name. If the execution of 
a function is interrupted (leaving it either suspended , or pendent (See 
Section 7) , the local objects retain their dominant position, during the 
execution of subsequent APL operations, until such time as the halted 
function is completed. However, system commands and the del form of 
function definition (see below) continue to reference global objects 
under these circumstances. 

The localization of names is dynamic, in the sense that it has no 
effect except when the defined function is being executed. Furthermore, 
when a defined function uses another defined function during its 
execution, a name localized in the first (or outer) function continues 
to exclude global objects of the same name from the purview of the 
second (or inner) function. This means that a name localized in an 
outer function has the significance assigned to it in that function when 
used without further localization in an inner function. The same name 
localized in a sequence of nested functions has the significance 
assigned to it at the innermost level of execution. 

The shadowing of a name by localization is complete, in the sense 
that once a name has been localized its global and outer values are 
nullified, even if no significance is assigned to it during execution of 
the function in which it is localized. 

BRANCHING AND STATEMENT NUMBERS 

Statements in a function are normally executed successively, from 
top to bottom, and execution terminates at the end of the last statement 
in the sequence. This normal order can be modified by branches . 
Branches are used in the construction of iterative procedures, in 
choosing one out of a number of possible continuations, or in other 
situations where decisions are made during the course of function 
execution. 

To facilitate branching, the successive statements in a function 
definition have reference numbers associated with them, starting with 
the number one for the first statement in the function body and 
continuing with successive integers, as required. Thus, the expression 
+4 denotes a branch to the fourth statement in the function body, and 
when executed causes statement t to be executed next, regardless of 
where the branch statement itself occurs. (In particular -+-M- may be 
statement 4, in which case the system will simply execute this "tight 
loop" indefinitely, until interrupted by an action from the keyboard. 
This is a trap to be avoided.) 

A branch statement always starts with the branch arrow (or right 
arrow ) on the left, and this can be followed by any expression. For the 
statement to be effective, however, the expression must evaluate to an 
integer, to a vector whose first element is an integer, or to an empty 
vector; any other value results in a DOMAIN or RANK error. If the 

Section 6: Function Definition 61 



expression evaluates to a valid result, then the following rules apply: 

1 . If the result is an empty vector the branch is vacuous and 
execution continues with the next statement in the function if 
there is one, or else the function terminates. 

2. If the result is the number of a statement in the function then 
that statement is the next to be executed. 

3. If the result is a number out of the range of statement numbers 
in the function, then the function terminates. The number o and 
all negative integers are outside of the range of statement 
numbers for any function. 

Since zero is often a convenient result to compute, and it is not 
the number of a statement in the body of any function, it is often used 
as a standard value for a branch intended to end the execution of a 
function. It should be noted that in the function definition mode 
described below, zero is used to refer to the header. This has no 
bearing on its use as a target for a branch. 

An example of the use of a branch statement is shown in the 
following function, which computes the greatest common divisor of two 
scalars: 

Z+M GCD N 

Z+M 

M+M\N 

N+Z 

-*(0*M)/1 

The compression function in the form U/V gives V if U is equal to 
one, and an empty vector if U is equal to zero. Thus, the fourth 
statement in GCD is a branch statement which causes a branch to the 
first statement when the condition q*m is true, and a branch with an 
empty vector argument, that is, normal sequence, when the condition is 
false. In this case, there is no next statement and so execution of the 
function ends. 

LABELS 

If a statement occurring in the body of a function definition is 
prefaced by a name and a colon, then the name is assigned a value equal 
to the statement number. A name used in this way is called a label . 
Labels are used to advantage when it is expected that a function 
definition may be changed for one reason or another, since a label 
automatically assumes the new value of the statement number of its 
associated statement as other statements are inserted or deleted. 

The name of a label is local to the function in which it appears, 
and must be distinct from other label names and from the local names in 
the header. 

A label name may not appear immediately to the left of a 
specification arrow. In effect it acts like a (local) constant. 

COMMENTS 

The lamp symbol pi (the cap-null) signifies that what follows it is 
a comment, for illumination only and not to be executed; it may occur 
only as the first character in a statement. 



62 APL Language 



FUNCTION EDITING - THE V FORM 

The functions QCR and QFX together form a basis for establishing 
and revising functions. Convenient definition editing with them, 
however, requires the use of prepared editing functions which must be 
defined, stored in a library, and explicitly activated when needed. The 
del form described here provides an alternative facility for function 
entry and revision which is always present for use. 

When the user enters the del character (v) followed by the name of 
a defined function, the system responds by displaying [tf+1] , where N is 
the number of statements in the function. It is now possible to: 

add, insert, or replace statements 

replace the header 

modify the header or a statement 

delete a statement 

display all or part of the definition 

A new function is started by entering the desired header on the 
same line as the opening V. Once the function definition mode has thus 
been entered, the treatment of a new function is identical to that for a 
function already defined. 

ADDING A STATEMENT 

If the response to the display of statement number [tf+1] is a 
statement, it is accepted as a line added at the end of the definition. 
The system response is the display [W+2] . Additional statements may 
continue to be added to the definition in this manner. If an empty 
statement is entered, the system will re-display the line number in 
brackets. 

INSERTING OR REPLACING A STATEMENT 

If the response to the statement number displayed by the system is 
IN] , where N is any positive number with or without a fractional part, 
the system will display INI . A statement entered will replace an 
existing statement N. 

The system continues by displaying the next appropriate number. 
For example, if the statement number entered was [3] , the next number 
displayed will be [4] ; if [3.02] , then [3.03] ; if [3.29] then [3.3] , 
and so forth. 

A statement may be submitted with line number [#]; it will be 
inserted or will replace an existing statement in the manner described. 
The response of the system in this case is to display the next statement 
number. 

REPLACING THE HEADER 

If the user enters [0] , the system responds by displaying [0] . 
The user may now enter any legal header, which will replace the existing 
header. Following this, the system displays [1] . The entire operation 
may be carried out by entering [0] and, on the same line, the header. 

DELETING A STATEMENT 

One or more statements may be deleted by entering in brackets a 
delta followed by one or more statement numbers, for example, [A2 7 3]. 
The response of the system is to display the statement number that 
follows the last number in the list. In the example, the response will 
be [4]. 

Section 6: Function Definition 63 



EDITING A STATEMENT OR HEADER 

Statement N can be modified by the following mechanism: 

1. Enter [AW] where M is an integer. The header is referred to 
by using o for N. 

2. Statement N or the header is automatically displayed and the 
cursor stops under position M, which is counted from the left 
margin. 

3. A letter or decimal digit or the symbol / may be typed under 
any of the positions in the display. Any other characters 
typed in this mode are ignored. The ordinary rules for 
editing before entry (such as backspace and linefeed) apply. 

4. The line is re-displayed. Each character understruck by a / 
is deleted, each character understruck by a digit K is 
preceded by K added spaces, and each character understruck by 
a letter is preceded by 5*R spaces, where R is the position of 
the letter in the alphabet. For example, the letter C will 
produce 15 spaces. Finally, the cursor moves to the first 
injected space and awaits the typing of modifications in the 
usual manner . The final effect is as if the entry had been - 
made entirely from the keyboard; in particular, a completely 
blank sequence leaves the line unchanged. 

If a statement number itself is changed from N to P during the 
editing procedure the statement affected is determined by the new 
statement number P; hence statement N remains unchanged. This permits 
statements to be moved, with or without modification. 

If an attempt to display a line would exceed the printing width 
(determined by DPW) this form of editing is not applicable. Such a 
condition may arise if the line is too long to start with, or if too 
many spaces have been requested for insertion. 

ADDING TO A STATEMENT OR HEADER 

One or more characters can be added to the end of statement N, or 
statement N can be corrected, by entering [iVDO]. In response, the 
system displays statement N; the cursor is positioned at the end of the 
statement, and the keyboard unlocks. The statement may be extended, or 
modified by using the normal revision procedures for entry. In 
response, the system displays the next statement number and awaits 
entry. 

The header may be modified in this way by entering [0[]0]. 

FUNCTION DISPLAY 

The canonical representation of a function includes the header and 
body displayed as a character matrix. The V form permits display of a 
canonical representation modified as follows: 

1. Labelled lines and comments are offset one space to the left. 

2. Statement numbers in brackets are appended to the left of the 
statements. 

3. A del character (7) is prefixed to the header, separated by 
one space. 

4. A final line is added, consisting of spaces and a del 
character, aligned with the del character which prefixes the 
header. 



64 APL Language 



Shown are the canonical representation and function display of a 
function for computing the determinant of a matrix: 

UCR'DET' VDETLOlV 

Z+DET A;B;P;I V Z+DET A;B;P;I 

I+QIO [ 1 3 I+QIO 

Z«-l [2] Z<-1 

L:F«-( U[;J])ir/UC;I] [3] L : P-K \A C ;I ] ) i \ I \A C ;I] 

+(P=I)/LL [4] -*{P=I)/LL 

AiI,P;l<-AlP,I;l [5] 4[I ,P; l-MLP.I ; ] 

Z«--Z [6] Z-e--Z 

LL:Z-e-ZxBfi4[I;J] [7] LL : Z+-ZXB+-4 [ J ; J] 

+ (0 1 v.=Z,l + p4)/0 [8] +(0 1 v.=Z,l + pi4)/0 

4 + 1 1 +4-U[;J3*B)°.x4[I; ] [9] 4+1 1 + A- {A [ ;X]tB ) <> . x4 [I ; ] 

-»-£ [10] ->L 

^EVALUATES A DETERMINANT [11] ^EVALUATES A DETERMINANT 

V 

The display of a function can be obtained by typing CD]. After 
the display, the system displays [ff+1] where ff is the number of 
statements in the function. 

Statement N can be displayed by typing [ffQ]. After display the 
system types INI. Entering LQKl causes display of all statements from 
K onwards. After the display the system displays IN +11 where N is the 
number of statements in the function. 

LEAVING TIfE V FORM 

The del form may be left by typing a V on a line by itself, or 
as the last character on any entry except one which enters a comment 
statement. 

In particular, it can follow a request for display or a function 
statement, and either can be incorporated in the same entry that both 
opens and closes the definition mode, as in VDETlQlV or VDETilOl+L ,LV. 
On leaving the del form, the statements are reordered according to 
their statement numbers and the statement numbers are replaced by the 
integers 1, 2, 3, and so on. 

A function definition can be locked by either opening or closing 
the definition mode with a del-tilde, V. The use of this is explained 
in Section 7. 



Section 6: Function Definition 65 



SECTION 7: FUNCTION EXECUTION 

A defined function may be used like a primitive function, except 
that it may not be the argument of a primitive operator. In particular, 
a defined function may be used within its own definition or that of 
another defined function. When a function is called, or put into use, 
its execution begins with the first statement, and continues with 
successive statements except as this sequence is altered by branch 
instructions . 

Consider the function OVERTIME: 

PAY+R OVERTIME H-.TIME 

TIME^0[^0-H 

PAY*- Rxl.5*TIME 

If this function is invoked by a statement such as X OVERTIME I the 
effect is to assign to the local name R the value of X and to H the 
value of Y, and then execute the body of the function OVERTIME. Except 
for having a value assigned initially, the argument variable is treated 
as any other local variable .and, in particular, may be respecified 
within the function. 

A function like OVERTIME, which produces an explicit result, may 
properly be used in compound expressions. In the OVERTIME function the 
last value received by PAY in the course of execution is the explicit 
result of the function. For example: 

YTDAT 
100 200 150 

YTDAT+YTDAT+0T+-5 7 6 OVERTIME 3 5 40 4 5 

OT 
45 

YTDAT 
100 200 195 

PAY, itself, is a local variable and therefore has no significance after 
the function is executed: 

PAY 
VALUE ERROR 
PAY 



HALTED EXECUTION 

The execution of a function F may be stopped before completion in 
a variety of ways: by an error report, by an attention signal, or by the 
stop control treated below. When this happens the function is said to 
be suspended , and its progress can be resumed by entering a branch- 
statement from the keyboard. Whatever the reason for suspension, the 
name of the function is displayed, with a statement number beside it. 
In the case of an error stop or an interrupt the statement itself is 
also displayed, with an appropriate message and an indication of the 
point of interruption. Unless a specification appears in the statement 
to the right of this point, the state of the computation has been 
restored to the condition obtaining before the statement started to 
execute . 

In general, therefore, the displayed number is that of the 
statement that should be executed next if the function is to continue 
normally. Resumption of execution at that point can be accomplished by 
entering a branch to that number specifically, a branch to an empty 
vector, or a branch to QLC. Entering -*0 , or a branch to another number 

66 APL Language 



outside the range of statement numbers, causes an immediate exit from 
the function and it is no longer suspended. 

In the suspended state all normal activities are possible, but 
names used refer to their local significance, if any. The system is in 
a condition to execute statements or system commands, resume execution 
of the function at an arbitrary point, or enter definition mode to work 
on any function which is not pendent (see below) . In particular, the 
suspended function can be edited at this point (if it is not itself 
pendent from a previous use) . 

STATE INDICATOR 

Entering the system command )SI causes a display of the state 
indicator ; a typical display has the following form: 

)SI 

Hill * 

F[2] 

G[3] 

This display indicates that execution was halted before completing 
(perhaps before starting) execution of statement 7 of function H, that 
the current use of function H was invoked in statement 2 of function F, 
and that the use of function F was in turn invoked in statement 3 of C. 
The * appearing to the right of ff[7] indicates that the function H is 
suspended. The functions G and F are said to be pendent , because their 
execution cannot be restarted directly, but only as a consequence of 
function H resuming its course of execution. The term halted is used 
to describe a function which is either pendent or suspended. 

Further functions can be invoked when in the suspended state. 
Thus, if G were now invoked and a further suspension occurred in 
statement 5 of Q , itself invoked in statement 8 of G, a subsequent 
display of the state indicator would appear as follows: 





)SI 


«L5] 


* 


GC8] 




ff[7] 


* 


GC2] 




F[3] 





Since the line counter, ULC , holds the current statement numbers 
of functions that are in process of execution, its value at this point 
would be the vector 5 8 7 2 3. The sequence from the last to the 
preceding suspension can be cleared by entering a right arrow (->■) . This 
behavior is illustrated by continuing the foregoing example as follows! 



fl[7] 
G[2] 
**[3] 

7 2 3 



)SI 



ULC 



Repeated use of •*■ will clear the state indicator completely, and restore 
ULC to an empty vector. The cleared state indicator displays as a blank 
line. 



Section 7: Function Execution 67 



STATE INDICATOR DAMAGE 

If the name of a function occurs in the state indicator list, then 
erasure of the function or replacement of the function by copying a 
function with the same name (even another instance of the same function) 
will make it impossible for the original course of execution to be 
resumed. In such an event an SI DAMAGE report is given. In addition, 
some APL systems will give an SI DAMAGE report if a suspended function 
is edited to change the order of its labels or to modify its header. 

If an SI DAMAGE report is given for a suspended function, it will 
not be possible to resume its execution by entering a branch statement, 
but the function can be invoked anew, with or without prior clearance of 
the state indicator. 

In case of SI DAMAGE, display of the state indicator will show the 
damage, possibly by a blank where the function name should have appeared 
or by some explicit indicator or both. 

TRACE CONTROL 

A trace is an automatic display of information generated by the 
execution of a function as it progresses. In a complete trace of a 
function, the number of each statement executed is displayed in 
brackets, preceded by the function name and followed by the final value 
produced by the statement. The trace of a branch statement shows a 
branch arrow followed by the number of the next statement to be 
executed. The trace is useful in analyzing the behavior of a defined 
function, particularly during its design. 

The tracing of a function PROFIT. is controlled by the trace 
control for PROFIT, denoted by TLPROFIT. If one sets T A PR FIT*- 2 3 5 
then statements 2, 3, and 5 will be traced in any subsequent execution 
of PROFIT. TLPROFIT+xQ discontinues tracing of PROFIT. A complete 
trace of PROFIT is obtained by ThPROFIT+xN , where N is the number of 
statements in PROFIT. In general, the trace control for any function is 
designated by prefixing TA to the function name. 

STOP CONTROL 

A function can be caused to execute up to a certain statement and 
then stop in the suspended state. This is frequently useful in 
analyzing a function, for example by experimenting with local variables 
or intermediate results. The stops are set by the stop control in the 
same manner as the trace. For a function PROFIT, stops before "lines 4 
and 12 are executed would be set by entering S&PROFIT+H 12. 

At each stop, the function name and line number are displayed as 
described above for suspended functions. To go to the next stopping 
point after the first, execution must be explicitly restarted by 
entering an appropriate branch statement. 

Trace control and stop control can be used in conjunction. 
Moreover, either of the controls may be set within functions. In 
particular, they may be set by expressions which initiate tracing or 
stops as a result of certain conditions that may develop in the course 
of function execution, such as a particular variable taking on a 
particular value. They may only be used as the left argument of 
specification. They may not be used by themselves or as the argument to 
a function . 



68 APL Language 



LOCKED FUNCTIONS 

If the symbol ¥ (called del-tilde) is used instead of v to open or 
close a function definition, the function becomes locked . A locked 
function cannot be revised or displayed in any way. Any associated stop 
control or trace control is nullified after the function is locked. 

A locked function is treated essentially as a primitive, and its 
inner workings are concealed as much as possible. Execution of a locked 
function is terminated by any error ocurring within it, or by a strong 
interrupt. If execution stops the function is never suspended but is 
immediately abandoned. The message displayed for a stop is DOMAIN error 
if an error of any kind occured, WS FULL and the like if the stop 
resulted from a system limitation, or INTERRUPT. 

Moreover, a locked function is never pendent, and if an error 
occurs in any function invoked either directly or indirectly by a locked 
function, the execution of the entire sequence of nested functions is 
abandoned. If the outermost locked function was invoked by an unlocked 
function, that function will be suspended; if it was invoked by a 
keyboard entry the error message will be displayed with a copy of that 
statement. 

Similarly, when a weak interrupt is encountered in a locked 
function, or in any function that was ultimately invoked by a locked 
function, execution continues normally up to the first interruptable 
point: either the next statement in an unlocked function that invoked 
the outermost locked function, or the completion of the keyboard entry 
that used this locked function. In the latter case, the weak interrupt 
has no net effect. 

Locked functions may be used to keep a function definition 
proprietary, or as part of a security scheme for protecting other 
proprietary information. They are also used to force the kind of 
behavior just described, which sometimes simplifies the use of 
applications . 

RECURSIVE FUNCTIONS 

A defined function whose name has not been made local and is used 
in the body of the function definition is said to be defined 
recursively . For example, one definition of the greatest common divisor 
function states that the greatest common divisor of zero and any number 
N is N; for any other pair of numbers it is the greatest common divisor 
of the residue of the second number by the first, and the first number. 
The words "greatest common divisor" are used in the definition. This 
suggests that a greatest common divisor function GCDR can be written 
whose canonical representation is: 

DCR * GCDR ' 
R+A GCDR B 

R+B 

-Ko=4)/o 

R+(A |B) GCDR A 

18 GCDR 45 
9 

This can be compared to the equivalent function defined iteratively in 
Section 6. 

Executing an erroneously defined recursive function will often 
result in a WS FULL report. The non-trivial execution of a properly 
defined recursive function may also have this effect because of the very 
deep nesting of function calls that is often required. 

Section 7: Function Execution 69 



TERMINAL INPUT AND OUTPUT 

In many significant applications, such as text processing, for 
example, it is necessary that the user supply information as the 
execution of the application programs progresses. It is also often 
convenient, even in the use of an isolated function, to supply 
information in response to a request, rather then as arguments to the 
function as part of the original entry. This is illustrated by 
considering the use of the function CI, which determines the growth of a 
unit amount invested at periodic interest rate R for number of periods 
T: 

OCR' CI 1 
A+R CI T 
A<-(1+R)*T 

For example, the value of 1000 dollars at 5 per cent for 7 years, 
compounded quarterly, might be found by: 

1000 x (.05*4) CI 7x4 
1415.992304 

The casual user of such a function might, however, find it difficult to 
remember which argument of CI is which, how to adjust the rate and 
period stated in years for the frequency of compounding, and whether the 
interest rate is to be entered as the actual rate (for example, .05) or 
as a percentage (for example, 5). An exchange of the following form 
might be more suitable: 

INVEST 
ENTER CAPITAL AMOUNT IN DOLLARS 
D: 

1000 
ENTER NUMBER OF TIMES COMPOUNDED IN ONE YEAR 
□ : 

4 
ENTER ANNUAL INTEREST RATE IN PERCENT 
D: 

5 
ENTER PERIOD IN YEARS 
D: 

7 
VALUE IS 1415.992304 

It is necessary that each of the entries (1000, 4, 5, and 7) 
occurring in such an exchange be accepted not as an ordinary entry 
(which would only evoke the response 1000, etc.), but as data to be used 
within the function INVEST. Facilities for this are provided in two 
ways, termed evaluate d input , and character input . A definition of the 
function INVEST, which uses evaluated input, is as follows: 

UCR' INVEST' 
INVEST ;CiR;T;F 

' ENTER CAPITAL AMOUNT IN DOLLARS* 
C*-D 

'ENTER NUMBER OF TIMES COMPOUNDED IN ONE YEAR 1 
F+0 

'ENTER ANNUAL INTEREST RATE IN PER CENT' 
R+U+FxlOO 

'ENTER PERIOD IN YEARS' 
T-f-FxQ 
'VALUE IS ' ,vCxR CI T 

The function NEWSTOCK in the Introduction (Section 1) is an example of 
the use of both character input and bare output (discussed below) . 

70 APL Language 



EVALUATED INPUT 

The quad symbol Q appearing anywhere other than immediately to the 
left of a specification arrow denotes request for keyboard input as 
follows: the two symbols D: are displayed, and the keyboard is unlocked 
on the next line, indented from the left margin. Any valid expression 
entered at this point is evaluated, and the result substituted for the 
quad. Suppose F is a function whose definition includes a quad symbol: 

OCR ' F ' 
Z-f-F 
Z-s-l+xQ 

F 
D: 

3 + 2 
20 

An invalid entry in response to a request for quad input causes an 
appropriate error report, after which input is again awaited. For 
example, entering an expression which has no result produces a value 
error. Function definition mode (the editing or display of functions, 
or creation of new functions) is not permitted during Q entry. In 
general, a system command entered during Q input is executed, but the 
system's response to the command is not treated as a response to D- 
After execution of a command, valid input is again awaited (unless the 
command was one which replaced the contents of the active workspace) . 
An empty input (one containing nothing other than zero or more spaces) 
is rejected and the system again awaits input. 

INTERRUPTING EVALUATED INPUT 

Execution of a defined function containing a request for Q input 
can be interrupted at the statement containing the D by entering a 
statement which has no value (for example <t ' ' or a branch statement, or 
any defined function which does not return a result) . This suspends 
execution of the statement containing the U, with the report VALUE 
ERROR. A command that requires saving the workspace (either SAVE or 
CONTINUE, described in Section 8), issued during a request for □ input, 
also interrupts the statement containing the Q before carrying out the 
command . 

The response ■+ entered in response to a Q abandons execution of 
the function and any pendent functions leading up to it. 

CHARACTER INPUT 

The quote-quad symbol H (that is-, a quad overstruck with a quote) 
is a request for character input: entry is permitted at the left margin 
and data entered are accepted as characters. For example: 

X-s-B 
CAN'T (Quote-quad input, not indented) 

X 
CAN'T 

INTERRUPTING CHARACTER INPUT 

Request for B input can be interrupted,, in the case of certain 
typewriter terminals, by entering the three letters OUT, in that order, 
but with a backspace between each pair so that they all overstrike. 
This interrupts execution, but does not cause an exit from a defined 
function. 

Section 7: Function Execution 71 



NORMAL OUTPUT 

The quad symbol appearing immediately to the left of a 
specification arrow indicates that the value of the expression to the 
right of the arrow is to be displayed in the standard format (subject to 
the printing precision DPP and the printing width QPW) . Hence, Q+x is 
equivalent to the statement X. The longer form Q+x is useful when 
employing multiple specification. For example, U+Q+X*2 assigns to Q the 
value X*2 and then prints the value of J* 2. 

The maximum length of a line of normal display (measured in 
characters) is called the printing width , and is given by the value of 
the system variable QPW. The maximum and minimum effective values of 
the printing width depend upon the system being used, and the 
appropriate user's guide should be consulted. A display whose lines 
exceed the printing width is ended at or before the maximum length, and 
continued on subsequent lines. 

BARE OUTPUT 

Normal output includes a concluding new line signal so that the 
succeeding display (either input or output) will begin at a standard 
position on the following line. Bare output, denoted by expressions of 
the form Ch-X does not include this signal if it is followed either by 
another bare output or by character input (of the form X+B) . 

Character input following a bare output is treated as though the 
user had spaced over to the position occupied at the conclusion of the 
bare output, so that the characters received in response will normally 
be prefixed by a number of space characters. This allows for the 
possibility that, after the keyboard is unlocked, the user backspaces 
into the area occupied by the preceding output. The following function 
prompts the user with whatever message is supplied as its argument, and 
evaluates the response: 

UCR' PROMPT* 
Z+-PROMPT MSG 
B+-MSG 
Z-HD 

Using such a function, the expression: 

PROMPT 'ENTER CAPITAL: • 
would have the following effect: 
displayed by system 

ENTER CAPITAL: "lOOO 



entered by user 

The value of Z is as many blank characters as there are characters 
in MSG, followed by the characters entered by the user. In this case Z 
will have fifteen blanks followed by the character '1000'. 

The new line signals that would be supplied by the system in order 
to break lines that exceed the printing width are not supplied with bare 
output. However, since an expression of the form E+X entered directly 
from the keyboard (rather than being executed as part of a defined 
function) must necessarily be followed by another keyboard' entry, the 
output it causes is concluded with a new line signal. The effect is in 
this case indistinguishable from normal output, except for the 
possibility of exceeding the printing width limitation. 

72 APL Language 



SECTION 8: SYSTEM COMMANDS 



An APL system recognizes two broad classes of instructions, 
statements and system commands . System commands control the initiation 
and termination of a work session, saving and reactivating copies of a 
workspace, and transferring data from one workspace to another. 

System commands can be invoked only by individual entries from the 
keyboard and cannot be executed dynamically as part of a defined 
function. They are prefixed by a right parenthesis. 



They will be 



The system commands are summarized in Figure 8.1 
discussed under three main headings: 

1. The active workspace. 

a. Action. 

b. Inquiry. 

2. Workspace storage and retrieval. 

a. Action. 

b. Inquiry. 

3. Access to the system. 

A command that is not recognizable, or is improperly formed, is 
rejected with the report INCORRECT COMMAND. Certain commands may also 
result in more specific trouble reports; these are discussed in the 
appropriate context and are summarized in Figure 8.2. 

Once its execution has started, a system command cannot be 
interrupted, although display of the system's response to the command 
can be suppressed by an interrupt signal. 

In the text that follows, each system command is shown in a sample 
form. In use, the appropriate names or numbers should, of course, be 
substituted for those shown. 



A 

N 

USERNO 

LIBNO 

WSNAME 
GRPNAME 
OB J NAME 

PASS WD 
NEWPASS 
[ ] 



A letter of the alphabet. 

A number. 

A user account number. 

A library number (that is, either a 
user account number or a public 
library number) . 

A workspace name. 

A group name. 

A name of an object within a 
workspace (that is, a function, a 
variable, or a group) . 

A password, which must match the 
previously set value. 

A new password, which need not match 
the previously set value. 

Items enclosed in brackets may in 
some circumstances be omitted. 



Section 8: System Commands 73 



FORM 


PURPOSE 


NORMAL RESPONSE 


TROUBLE REPORTS 


TERMINAL CONTROL COMMANDS 












)number [pass] 


Identify user and start use of APL 


[public-adc 

header 

system 


Iress] 


1 5 


12 13 14 
















[SAVED time date] 






^CONTINUE [newpass] 


Replace ws CONTINUE by copy of active ws and 
end use of APL 


[time date 

header 

account 


CONTINUE] 


4 1t 




) CONTINUE HOLD [newpass] 


Replace ws CONTINUE by copy of active ws, end 
use of APL, but hold connection 


[time date 

header 

account 


CONTINUE] 


4 M 




)OFF [newpass] 


End use of APL 


header 

account 

header 




4 




)OFF HOLD [newpass] 


End use of APL, but hold connection 




4 








account 








ACTIVE WORKSPACE CONTROL COMMANDS 










) CLEAR 


Activate a clear ws 


CLEAR WS 




4 




)COPY wsid [pass] 


Copy all global objects from named ws into 
active ws 


SAVED time 


date 


2 3 


4 16 17 18 19 20 


)COPY wsid [pass] names 


Copy global objects named from designated ws 
into active ws 


SAVED time 


date 


2 3 


4 7 16 17 18 19 20 


) ERASE [names]. 


Erase global objects named from active ws 






4 7 


16 


) GROUP names 


Gather objects into (or disperse) a group 
(first name designates group) 






4 8 


17 18 


)LOAD wsid [pass] 


Activate copy of named ws 


SAVED time 


date 


3 4 


18 19 


)PCOPY wsid [pass] 


Copy all objects from designated ws not named 
in active ws 


SAVED time 


date 


2 3 


4 6 16 17 18 19 20 


)PCOPY wsid [pass] names 


Copy objects designated that are not named in 
active ws 


SAVED time 


date 


2 3 


4 « 7 16 17 18 19 20 


) SYMBOLS number 


Change maximum number of symbols in ws to 
number 


WAS number 




4 




)WSID wsid [newpass] 


Change identification of active ws 


WAS wsid 




4 




LIBRARY CONTROL COMMANDS 












)DROP wsid 


Drop ws from library 


time date 




3 4 


20 


)SAVE 


Place copy of active ws in library 


time date wsid 


3 4 


9 10 11 18 


)SAVE wsid [newpass] 


Replace named ws by copy of active ws 


time date 




3 4 


9 10 11 18 


INQUIRY COMMANDS 












) FNS [alphabetic] 


List defined functions (whose initials follow 
given character in alphabet) 


[names] 




4 




)GRP name 


List members of named group 


[names] 




4 V 




)GRPS [alphabetic] 


List groups (whose initials follow 
given character of alphabet) 


[names] 




4 




)LIB [number] [alphabetic] 


List workspaces in designated library (whose 
Initials follow given character in alphabet) 


[names] 




3 4 




)SI 


List halted functions 


state-indicator 


4 




)3IV 


List halted functions and associated local 


state-indicator and 


4 






names 


names 








) SYMBOLS 


Give maximum number of names in ws 


IS number 




4 




)VARS [alphabetic! 


List global variables (whose initials follow 
given character in alphabet) 


[names] 




4 




)WSID 


Give wsid of active ws 


[number] name 


4 




Notes: 1. Items in brack* 


sts are optional 












2. Abbreviations < 


snd meanings: 












ws \ 


7orkspace 












pass < 


s colon possibly followed by a password 












newpass < 


i pass that does not have to match a previous p 


as sword 










header t 


i port number, time of day, date, and user-code 












account < 

< 


rives the connect time and compute time since 1 
ind since beginning of the accounting period 


ast start 










wsid < 


i ws name possibly preceded by a library number 












public-address 


a message to users of the system 












3. The commands )l 


IRASEt )FNS. and )VARS have variants that are s 


ystem functions 








(see Qgx and Qj 


?C) . 













Figure 8.1: System Commands 



74 APL Language 



No. 



TROUBLE REPORT 



1 ALREADY SIGNED ON 

2 DEFN ERROR 

3 IMPROPER LIBRARY REFERENCE 

<* INCORRECT COMMAND 

5 INCORRECT SIGN -ON 

6 NOT COPIED: names 

7 NOT FOUND : purported names 

8 NOT GROUPED. NAME IN USE 

9 NOT SAVED, THIS WS IS CLEAR 

10 NOT SAVED, THIS US IS wsid 

11 NOT SAVED, WS QUOTA USED UP 

12 NUMBER IN USE 

13 NUMBER LOCKED OUT 

14 NUMBER NOT IN SYSTEM 

15 RESEND 

16 SI DAMAGE 

17 SYMBOL TABLE FULL 

18 WS FULL 

19 WS LOCKED 

20 WS NOT FOUND 



Meaning 



WS 



APL already in use at terminal 



Attempted copy or protected copy of 
function definition as response to 
□ input request (on some systems) 

1) Number is not a library number, or 

2) Attempted save into alien library, 
or 3) Attempted reference to alien 
CONTINUE WS 



Global homonyms in active ws are 
protected 

Ws does not contain global objects 
with purported names 

First name is name of a global 
function or variab.le 

A clear ws has no name and cannot be 
stored 

Attempted replacement of a stored ws 
whose identification does not match 
that of the active ws 

Allotted number of stored wss 
previously reached 



Authorization for use of number has 
been withdrawn 

1) Number entered is not an account 
number, or 2) Password missing, or 
3) Wrong password used 

Transmission failure or more than the 
implementation allowed number of 
characters entered in one line 

State indicator damaged while 
performing an ) ERASE or )C0PY command 

Too many names used 



Remedy 



1) To display account number, use OAI 

2) To change account number, execute 

)0FF HOLD or ) CONTINUE HOLD and 
sign on 



Workspace full, possibly because of 

1 ) Temporary values produced during 
evaluation of an expression, or 

2) Value assigned to shared variable 
by partner. 

1) Password missing, or 

2) Wrong password used 

No stored ws with given identification 



1) Use different name for group, or 

2) Erase global object if not needed 



Remove active ws, then store 



1 ) Drop an unneeded ws , or 

2) Ask APL operator to increase quota 

Consult APL operator 
Consult APL operator 

Consult APL operator 



If chronic, redial or have terminal 
or phone repaired 



Erase objects not needed, save ws, 
clear active ws, and perhaps change 
limit, using )SYMB0LS, copy the 
saved ws and rename the active ws 

1) Erase objects not needed, or 

2) Clear state indicator, or 

3) Revise method of calculation 



Figure 8.2: Trouble Reports 



Section 8: 



System Commands 75 



Items enclosed in angles may in some 
circumstances be omitted, and, where 
omitted, the system supplies values 
from the existing user 
identification, workspace 
identification, or previously 
established password. 



COMMANDS THAT MODIFY THE WORKSPACE ENVIRONMENT 

The following system commands affect the active workspace, the 
environment in which computation takes place and in which names have 
meaning. In particular, the active workspace contains the settings of 
the state indicator (discussed in Section 7) and other elements of the 
computing environment, mediated by several of the system variables 
(discussed in Section 4) . 



) CLEAR 



This command is used to make a fresh start, discarding the 
contents of the active workspace, and resetting the 
environment to standard initial values (see Figure 8.3). At 
sign-on, the user receives a clear workspace characterized by 
these same, initial values, unless the workspace CONTINUE was 
automatically loaded. 



Symbol table size 
Index origin, 010 
Latent expression, QLX 
Line counter, QLC 
State indicator 
Workspace name 
Workspace password 
Printing precision, DPP 
Printing width, UPW 
Comparison tolerance, OCT 
Random link, ORL 
Work area available, QWA 



* 256- 
1 

Empty 
Empty 
Cleared 

None (CLEAR WS) 
None 

* 10 

* 120 

* 1E~13 

* 16807 

* Depends on the local 
installation, and, in 
some systems , upon 
options selected by 
the user. 



* Items marked with an asterisk have values which 
may vary from system to system. The values shown 
are widely used. 

Figure 8.3. Environment Within a Clear Workspace 



76 APL Language 



) SYMBOLS N 

Sets the size of the symbol table, that is, the maximum number 
of names that may occur in the workspace. (Note that the 
occurrence of a name includes not only the names of functions, 
variables, or groups themselves, but also any names occurring 
within their definitions) . New values of the maximum may be 
set only in a clear workspace. An attempt to change the 
maximum once the workspace is no longer clear, or to set it 
outside the range permitted by the system, is rejected with 
the report INCORRECT COMMAND. Valid use of the command 
results in the report WAS . . . , showing the former limit. 

)ERASE 10BJNAME1 0BJNAME2 0BJNAME3 ...] 

The global objects named are expunged from the workspace; 
shared variable offers with respect to any of them are 
retracted. If a name is the name of a group (see below) , the 
group and all of its members present in the workspace are 
erased. (If a member of a group is itself a group, xts 
definition is erased but not its members.) 

If a halted function is erased, the report SI DAMAGE is 
displayed, and the name of that function is replaced in the 
state indicator by blanks. It is not possible to resume the 
execution of an erased function, and the user should enter ■*■ 
one or more times to clear the state indicator of indications 
of damage. 

If an object named in the command cannot be found, the report 
NOT FOUND: is emitted, followed by a list of the objects not 
found . 

)COPY <LIBNO> WSNAME l-.PASSWDl < OBJNAME 1 ] L0BJNAME2 ...] > 

The indicated global objects (but not system variables) are 
copied from the indicated workspace (the source workspace) 
into the active workspace. The system reports the date and 
time at which the source workspace was saved. 

If the list of objects to be copied is omitted, all global 
objects' other than system variables are copied from the source 
workspace. 

If the indicated source workspace is for some reason 
unavailable, copying cannot take place. The possible errors 
in gaining access are the same as those discussed under the 
LOAD command, namely IMPROPER LIBRARY REFERENCE, WS NOT FOUND, 
WS LOCKED. 

When an object to be copied is a group, the group membership 
list is copied as well as all those of its members which exist 
as global objects in the source workspace. 

When an object to be copied has the same name as a global 
object in the active workspace, the copied object replaces it. 
If there was a shared variable offer with respect to the 
variable thus replaced, the offer is retracted. 

If names explicitly mentioned in the copy command are not the 
names of global objects in the source workspace, the system 
reports NOT FOUND: followed by a list of the objects not 
found . 

Section 8: System Commands 77 



Copy During Evaluated Input . A copy command can be entered 
while a request for evaluated input (□:) is pending. The 
objects copied will then exist in the workspace but do not 
become the value of D . The request for evaluated input is 
then repeated. However, definition mode may not be entered 
during evaluated input, and hence the definition of a function 
may not be copied during evaluated input. An attempt to do so 
is rejected with the report DEFN ERROR. The following trouble 
reports may arise during copying: 

WS FULL There is insufficient space to accommodate all the 
material to be copied. However, those objects copied before 
space was exhausted remain in the active workspace. 

SYMBOL TABLE FULL New names occurring in the copied material 
exhaust the capacity of the symbol table. Those objects 
copied before the symbol table was exhausted remain in the 
active workspace. 

SI DAMAGE A copied object has replaced the definition of a 
halted function, so that its halted execution cannot be 
resumed. The user should then enter -*■ enough times to clear 
the state indicator of indications of damage. 

)PCOPY <LIBNO> WSNAME L-.PASSWDl < OBJNAME L0BJNAME2 ...] > 

The protecting copy command works in the same way as the 
unprotecting copy, described above, except that a global 
object having the same name as one already present in the 
active workspace is not copied. If any object is not copied 
for this reason, the system reports NOT COPIED: followed by a 
list of the objects not copied. 

-GROUPING TO FACILITATE COPYING OR ERASURE 

It is frequently convenient to copy into the active workspace 
several related functions and variables, and to erase them when they are 
no longer needed. To facilitate such transfers, a group may be defined 
by supplying a list of names that are to be copied or erased together. 
Since the group's definition will exist in the workspace, it must have a 
name distinct from that of any global object in the workspace. 

The definition of a group consists of a list of names. It is not 
necessary that objects having those names exist in the workspace. When 
a copy command or an erase command mentions the name of a group, then 
not only the definition of that group but also all global objects whose 
names appear in the membership list are copied (or erased, as the case 
may be) . 

If the membership of a group A includes the name B of another 
group, the act of copying A causes the membership list of B to be 
copied, but copying does not extend further. That is, the objects 
referred to in the membership list of B are not copied. The same 
applies to erasure. If an object named in the membership list of a 
group does not exist in the workspace, it cannot be copied or erased, 
but no report is generated. 

)GROUP GRPNAME LGRPNAME1 L0BJNAME1 0BJNAME2 ...] 

A group having the name GRPNAME and consisting of the 
membership list shown is formed in the active workspace. If 

78 APL Language 



the name is already in use as the name of a group, the new 
membership list (possibly empty) supersedes the old. 

If a group is given an empty membership list, it is dispersed . 
Dispersal of a group has no effects on its members (whereas 
the command ) ERASE GRPNAME applied to a group expunges both 
the group definition and the members) . 

If the name of the group appears also as one of the members of 

the group, the former membership list is merged with the list 

provided in the command, thereby appending new names to the 
membership list. 

The system makes no acknowledgment of a successful grouping. 

An attempt to form a group having a name already in use as the 
name of a global variable or function in the workspace is 
rejected with the report NOT GROUPED, NAME IN USE. 

Since the membership list of a group requires space within the 
workspace, the attempt to form a group may find insufficient 
space in the workspace or in the symbol table, resulting in 
the trouble reports WS FULL or SYMBOL TABLE FULL. 



COMMANDS THAT MONITOR THE ACTIVE WORKSPACE 

The following commands report aspects of the workspace 
environment, but produce no change in it. 



) SYMBOLS 



)FNS U] 



Elicits the report IS ... showing the current maximum number 
of symbols. 



Reports a list of the global functions in the active 
workspace, in alphabetical order [starting with the letter 
indicated] . 



)VARS U] 



)GRPS [A] 



Reports a list of the global variables in the active 
workspace, in alphabetical order [starting with the letter 
indicated] . 



Reports a list of the groups in the active workspace, in 
alphabetical order [starting with the letter indicated] . 



)GRP GRPNAME 

Reports the membership of the group named GRPNAME. 



)SI 



Displays the state indicator, showing the status of halted 
functions, with the most recently halted first. The list 

Section 8: System Commands 79 



shows the name of the function and the number of the statement 
at which work is halted. The actions that a user can take 
with respect to a halted function are described in Section 7. 

Suspended functions are marked in the state indicator by an 
asterisk, while pendent functions appear on the state 
indicator list without an asterisk. The names of functions 
whose definitions have been damaged (by editing, copying, or 
erasing them while they are halted) are replaced by blanks in 
the state indicator. 



)SIV 



Displays the state indicator in the same way as )SI , but in 
addition, with each function listed, lists names that are 
local to its execution. 

COMMANDS FOR WORKSPACE STORAGE AND RETRIEVAL 

The user may request that a duplicate of the currently active 
workspace be saved for later use. When a duplicate of a saved workspace 
is subsequently re-activated, the entire environment of computation is 
restored as it was, except that variables which were shared in the 
active workspace are not automatically shared again when the workspace 
is reactivated. 

LIBRARIES OF SAVED WORKSPACES 

The set of workspaces saved for a particular user is called that 
user's library . Each workspace is identified by the user's account 
number and the name the user assigns to it. However, in referring to 
workspaces in one's own library, the account number may be omitted; the 
user's own number is supplied automatically. 

In systems with multiple users, it is often convenient to use 
functions or variables contributed by others. One user may activate an 
entire workspace saved by another user, or may copy from it selected 
items. To do so both the library number and the name of the desired 
workspace must be supplied. However, the system provides no way of 
learning either the account numbers or the names of workspaces belonging 
to other users. Thus a user may make use of material from the libraries 
of others only if they supply that information. In no case may a user 
add, change, or delete material from the library of another user. 

Certain libraries (usually identified by a particular group of 
library numbers) are not assigned to individual users, but are 
designated as public libraries. Any user may obtain a list of 
workspaces in a public library, and may use public workspaces. However, 
there may be restrictions on who can save, drop, or modify a workspace 
in a public library. In general, a public workspace can be re~saved or 
deleted only by the user who first saved it. 

NAMES AND PASSWORDS FOR WORKSPACES 

A saved workspace must be named. The name of a workspace may 
duplicate a name used for an APL object within the workspace. A 
password may be paired with the name of a workspace. Once this is done, 
any reference to the saved workspace (other than dropping it) must be 
accompanied by the password. 



80 APL Language 



The rules governing what workspace names are permissible and what 
passwords are permissible may differ from each other and from the rules 
governing names within a workspace. In particular, the number of 
significant characters in a workspace name or in a password may differ, 
and may be less than the number of significant characters in a name used 
within a workspace. Workspace names and passwords may be composed of 
alphabetic and numeric characters, but not spaces or special symbols; 
workspace names must begin with an alphabetic, but this restriction does 
not apply to passwords. 

)WSID <LIBNO> WSNAME l-.NEWPASS] 

Assigns to the active workspace the name indicated, and 
(optionally) the library number or the password indicated. 
Use of the colon with nothing following it assigns an empty 
password; that is, it removes a former password if there was 
one. If the active workspace is subsequently saved, future 
use of the saved workspace will require use of the password 
set here. 

Setting of the active workspace's identif cation is 
acknowledged by the report WAS . . . followed by the former 
name, but not the former password. 

)SAVE < <LIBNO> WSNAME <:NEWPASS> > 

A duplicate of the active workspace is saved (optionally, in 
the indicated public library, otherwise in the user's own 
library) under the indicated name, and (optionally) with the 
new password indicated. If the user number, workspace name, 
or password are omitted, they are supplied from the workspace 
identification. After saving, the active workspace has the 
same indentif ication (including account number, name, and 
password) as the saved workspace. 

Although saving does not affect the state of sharing in the 
active workspace, current values of the shared variables are 
saved in the stored copy. 

Saving is acknowledged by a report showing the date and time 
at which the workspace was saved. 

The command to save the active workspace may be rejected, with 
trouble reports as follows: 

IMPROPER LIBRARY REFERENCE The system does not permit a 
workspace to be saved in the private library of another user, 
or in a non-existent public- library, nor does it permit a 
workspace named CONTINUE to be saved in a public library. 

NOT SAVED, THIS WS IS ... Saving is not permitted when the 
name given in the command matches the identification of an 
existing saved workspace but does not match the identification 
of the active workspace. This restriction prevents the user 
from inadvertently overwriting one workspace with another. 

WS QUOTA USED UP Saving is permitted only while the number of 
workspaces currently saved or the space used by the saved 
workspaces is less than the user's allocation. Quotas are set 
by the system operator. 

WS FULL The workspace contains a shared variable whose value, 
when brought in to the workspace, would require for its 
storage more work area than is available in the workspace. 

Section 8: System Commands 81 



NO SPACE There is insufficient space in the system's 
auxiliary storage to accomodate the workspace. 

LIBRARY TABLE FULL The system's directory of saved workspaces 
lacks space in which to record this one. 

The last two problems cannot be remedied by the user's action 
but require intervention from the system manager to expand the 
system facilities. 

) CONTINUE WOLD] <:NEWPASS> 

The active workspace is saved under the name CONTINUE , and 
(unless a different password is specified) with the password 
previously assigned to the active workspace. Then the 
terminal is signed off in the same way as with the command 
)OFF, described below. Unless the CONTINUE workspace is 
password-protected, it will be automatically loaded at the 
next sign-on. 

The system operator has the power to force a sign off 
("bounce") some or all users. If a user is bounced, the 
system behaves as though the user had entered the command 
) CONTINUE. A ) CONTINUE is also executed automatically if the 
user's connection to the system is broken without a normal 
sign-off; see the discussion of "Automatic Saving After Line 
Drop," below. 

The command )CONTINUE may be rejected for the same reasons 
that apply to )SAVE , listed above. 

)L0AD <LIBNO> WSNAME L-.PASSWD] 

A duplicate of the indicated workspace (including its entire 
computing environment) becomes the user's active workspace. 
Shared variable offers in the former active workspace are 
retracted. Following a successful )LOAD, the system reports 
the date and time at which the loaded workspace was last 
saved. The system then immediately executes the latent 
expression {OLX) . 

Invalid requests to load a workspace may result in the 
following trouble reports: 

WS NOT FOUND The indicated workspace cannot be found. 

WS LOCKED The password supplied in the command does not match 
the password of the saved workspace, or is missing from the 
command when required. 

IMPROPER LIBRARY REFERENCE The user is ineligible to use the 
indicated library. 

)DROP <LIBNO> WSNAME 

The named workspace is removed from the user's library or from 
the indicated public library. The system reports the date and 
time. _ The password is not required to drop a saved workspace. 
Dropping a workspace has no effect on the active workspace. 



82 APL Language 



An attempt to drop a workspace saved by someone other than the 
user is rejected with the report IMPROPER LIBRARY REFERENCE . 
Reference to a non-existent workspace is rejected with the 
report WS NOT FOUND- 

AUTOMATIC SAVING AFTER LINE-DROP 

AND SPECIAL PROPERTIES OF THE CONTINUE WORKSPACE 

If the connection to the computer or host system is broken before 
a normal sign off, and the active workspace is not empty, the system 
acts as though the user had entered the command )CONTINUE , thereby 
saving the contents of the active workspace under the name CONTINUE - 
The CONTINUE workspace is intended solely for temporary storage. 
Regardless of the name of the active workspace, it can under these 
conditions be saved under the name CONTINUE- That is, a previously 
saved workspace named CONTINUE may be replaced by the active workspace 
without the protection against overwriting provided for other 
workspaces. 

Since any account may have a workspace named CONTINUE, to assure 
privacy the CONTINUE workspace of one user can not be loaded by another 
user, nor can it be saved in a public library. The workspace CONTINUE 
does not count as part of the user's quota of saved workspaces. 

COMMANDS REGARDING WORKSPACE STORAGE AND RETRIEVAL 



)WSID 



Reports the identification of the active workspace, showing 
the library number if other than the user's own, and the 
workspace name, but not the password. 



)LIB <LIBNO> [4] 

Displays the names of the workspaces in the user's private 
library or in the indicated public library. In systems in 
which the optional letter of the alphabet can be used the 
display is alphabetized. If the command is followed by a 
letter of the alphabet, the display begins with names starting 
with that letter. 

An attempt to display the list of workspaces in another user's 
private library or in a non-existent public library is 
rejected with the report IM-PROPER LIBRARY REFERENCE- 

ACCESS TO THE SYSTEM 

Each user of the system is assigned by the system manager an 
account identification used to identify data storage and charges for use 
of the system. The account identification is required in order to sign 
on. 

Each user is also assigned a quota indicating the maximum _ number 
or capacity of saved workspaces, and an interface quota indicating the 
maximum number of variables that may be shared simultaneously. 

The system manager may also establish a cpu limit for an account, 
limiting the amount of central processor time per keyboard entry. _ When 
the limit is reached, an interruption is made in the same way as if a 
strong interrupt had been signalled from the keyboard. 

Section 8: System Commands 83 



SIGN ON 



Before work can be started, a physical connection to the 
computer must first be established. This may require as 
little as turning a switch, or may require establishing a link 
from a dial-up terminal to a central computer, possibly 
passing through intermediary computing systems which are host 
to APL, depending on the system employed and the type of 
terminal device employed. 

Once communication is established, a numerical identification 
of the user must be provided to the system. The precise 
manner of providing this varies from system to system. 

At sign on, either a clear workspace or the CONTINUE 
workspace is activated, depending on the condition which 
terminated the preceding session, and the system in use. 

Successful sign on is acknowledged by a message showing the 
port number, the date and time, the user's name, and the 
system identification. This may be preceded by a broadcast 
message from the system operator. If CONTINUE was activated, 
the system reports the date and time at which it was saved. 

An attempt to sign on may be rejected, with one of the 
following reports: 

ALREADY SIGNED ON The terminal is in use, and must first be 
signed off (or bounced by the system operator) before a new 
sign-on can be accepted. 

NUMBER IN USE The indicated account number is in use at 
another port. This may arise either because another user is 
in fact using the account, or occasionally (perhaps because of 
an equipment problem) because the system did not complete 
disconnection at an earlier work session. 

NUMBER NOT IN SYSTEM This report means either that the 
indicated account has not been enrolled, or that the password 
supplied does not match the password last set. 

NUMBER LOCKED OUT Authorization for use of the account has 
been withdrawn. Workspaces saved in this library cannot be 
loaded or copied by anyone. 



SIGN OFF 

)OFF I HOLD] <:NEWPASS> 



An accounting report is displayed, showing the port number, 
date and time, and user code, followed by the connect time and 
central processor time used at the current session and 
cumulatively since the last accounting. 

If the word HOLD is used, the connection to the computer or 
host system is held for a brief period to accommodate sign on 
by another user. 

If a colon is used, the word following it (or none) will be 
the password for subsequent sign ons. 



84 APL Language 



)CONTINUE IH0LD~] <:NEWPASS> 



Because this command has the dual effects of saving the active 
workspace and signing the user off, it is described here and 
also in the section on workspace storage and retrieval. 

The user is signed off in the same manner as with )OFF, but 
the active workspace is first saved under the name CONTINUE. 
If a password is set, it will apply at subsequent sign-ons. 

The command may be rejected if it is impossible to save the 
CONTINUE workspace, either because the physical resources of 
the system are unable to accomodate it, or because of a full 
workspace produced when the value of a shared variable is 
transferred to the workspace. See the preceding discussion of 
the commands )SAVE and ) CONTINUE. 



Section 8: System Commands 85 



INDEX 



1050 terminal, 51. 



absolute value, 20. 
access, to APL system, 73. 
access control for shared 

variable, 52 53 55 57. 
access functions, isolation of, as 

programming technique, 4. 
access state of shared variable, 

55. 
account identification, 16 50 83. 
account information, 51 . 
activation, workspace, and 

execution of latent expression, 

50 82. 
activation, workspace, by load 

command, 2 50 51 82. 
active workspace, 2 15 50 51 73 79 

82. 
active workspace, system commands 

that affect, 73 79 82. 
adding statement, to function 

definition, 63. 
adding to statement, in function 

definition, 64. 
addition, 12 18 19. 
alpha , 12. 

alphabetic characters, 10 12. 
ALREADY SIGNED ON, 75 84. 
alternating sum, 25. 
alternating product, 26. 
and, logical, 12 18 20. 
announcement from system operator, 

received at sign on, 84. 
application package, workspace 

for, 2 6. 
arccos, 18 24. 
arcosh, 18 24. 
arcsin, 18 24. 
arctan, 14 18 24. 
argument, of a function, 13 66. 
arguments, number of. See 

valence, 
array, as primitive object, 7 14 

17. 
arsinh, 18. 
artanh, 18. 
atomic vector, 50 51. 
attention key, as interrupt 

signal, 10. 
automatic start of function 

execution upon load, 51. 
availability, of name, 49 60. 
axis, operator, 7 27 33 37. 



B 

backspace, 9 10 71. 
bar, 12. 



bare output, 72. 
base, 12. 
base null, 12. 
base-value, 42. 
BCD terminal, 51 . 
billing, system for, 2 6. 
binomial, 18 19 24 25. 
blank, as separator, 13. 
blank, in character constants, 13. 
body of a function, 7 59. 
boolean functions, 17 21. 
bounce, 82. 
bracket, 12. 

branch, control of sequence, 7 9 
61 . 



canonical representation, 47 48 59 

65. 
cap, 12. 
cap null, 12. 
card reader, communication through 

shared variables, 52. 
caret, to mark point at which 

correction was requested, 10. 
carrier return, omitted in bare 

output, 72. 
carrier return, to release entry 

statement, 9. 
catenate, 30. 
catenate, conformability 

requirements, 34. 
ceiling, 18 21. 
chaining, to join arrays. See 

catenate, laminate, 
character display, see format, 
character editing, of statements 

in function definition, 64. 
CHARACTER ERROR, 11. 
character input, 70. 
character input , interrupted , 71. 
character set, 10 12. 
character representation, 

function, 47 48 59 65. 
character representation, numbers, 

44. 
characteristics of APL, 4. 
characteristic vector, 30 39. 
characters, enterable from 

terminal , 9 . 
circle, 12 19. 
circle bar, 12. 
circle slope, 12. 
circle stile, 12. 
circular functions, 18 23. 
classification, names, 49. 
CLEAR, command, 74. 
clear workspace, 50 76. 
CLEAR WS, 50 76. 



Index 



87 



close shoe, 12. 

colon, 12 62. 

column, 27 41 . 

combinations, 18 19 24 25. 

comma, 12 33. 

comment, 62. 

communication, with processors 

external to APL, 7 52. 
comparison tolerance, 20 22 50 51 

76. 
complement, logical, 20. 
complex roots, undefined, 22. 
composite character, 10. 
compound expression, 14. 
compound interest, example, 1. 
compress, 30 36. 
compute time, 51. 
concurrent process, and shared 

variables, 52. 
conformability, 11 17 28 34. 
conjugate, 18. 20. 
connect time, 51 . 
connection, broken, 82 83. 
connection, establishing, 84. 
connection, hold, 74 82 84. 
constant, 10. 
continuation, output line that 

exceeds printing width, 72. 
CONTINUE, command, 74. 82 83. 
CONTINUE, workspace, 80 84. 
CONTINUE HOLD, command, 74 80 83. 
coordinate, array, 4 27 37. 
COPY, command, 71 74 77 78. 
copying, of function definition, 

59 71 77. 
correction of statement being 

entered , 9 . 
correction, of entry before 

release, 9. 
cos, 18 23. 
cosh, 18 23. 

coupling, degree of, 54 57. 
cup , 12. 
cursor, to indicate position of 

next entry, 9. 



D 



data, names used for, 1. 

data transformations, 43. 

date, 50 51. 

deal, 18 30 39. 

decimal point, in display, 45. 

decimal point, in entering 

numbers , 10. 
decode, 30 42. 
defined functions, control of 

sequence of execution in, 9 61 
defined functions, treated same 

Wciy as primitives, 7 66. 
definition error, 11 71. 
DEFN ERROR, 11 71 75 77 
degree of coupling, 54. 
del, 12. 
del stile, 12. 



del tilde, 12. 

delay, 48 50. 

deleting a statement, of function 

definition, 63. 
deletion, workspace. See drop, 
delta, 12. 
delta stile, 12. 
DESCRIBE, variable used to explain 

an application package, 2. 
determinant, function for, as 

example, 65. 
device, used to display computer's 

response, 1 . 
diagonal, 35. 
dieresis, 12. 

dimension, see shape or axis, 
disk-file, used in conjunction 

with APL, 1 . 
display, of function definition, 

63. 
display, of result of computation, 

1 9. 
distinguished names, 47. 
division, 12 18 19. 
division by zero, 17. 
domain, of scalar functions, 17. 
DOMAIN ERROR, 11. 
domain error, produced by locked 

function, 69. 
domino , 12 40. 
dot, 12. 
double attention, as strong 

interrupt, 10. 
down arrow , 12. 
downstile, character, 10 12. 
drop, 30 36. 
DROP, command, 74. 
dyadic, valence of function, 13. 
dyadic and mondaic forms of 

primitive functions, 18. 
dyadic functions, identity 

elements of, 19. 



E 



e, base of natural logarithm, 22. 
editing, of function definition, 

59 63 64. 
editing, of function header, 63 

64. 
empty array, 32. 
empty array, reduction over, 17 

26. 
empty branch, 62. 
encode, 30 42. 

entry, from keyboard, 1 7 9 70 71 
environment of computation, 47. 
epsilon, 12. 
equal, 12 18 19. 
ERASE, command, 74 77. 
erasure, dynamic, 49. 
error reports, for execute, 43. 
error report, form of, 10. 



88 



APL Language 



error report, table of, 11. 
error report, when evoked, 10. 
establishment, of function 

definition, 59. 
evaluated input, 70 71. 
evaluated input, during copy, 78. 
evaluated input, interrupted, 71. 
even roots, of negative numbers, 

undefined, 22. 
exclusive or, 21 . 
execute, 30 43. 
execute, error report, 43. 
execution, of defined function, 

66. 
execution, order of, 14. 
execution, sequence of statements 

in defined function, 61 66. 
exit, branch to, 62. 
exit, from function definition 

mode , 64. 
expand , 30 36 37. 
exponentiation, 22. 
exponential, 18 23. 
exponential form, see scaled form, 
expression, 9. 
expunge, object from workspace, 

48. 
extension of scalar function to 

array, 17. 



factorial, 18 24. 

false, number used to represent, 

20. 
first, selection of by take, 36. 
first axis, 37. 
fix, function definition, 47 48 

59. 
floor, 10 18 21 . 
FNS, command, 2 74 79. 
format, 30 ; ii Tj * 
function, defined, used in 

statement, 1 3 5 66. 
function, derivation of term, 13. 
function, establishment, 47. 
function, represented as character 

matrix, 6 47. 
function definition mode, 59 63 

64. 
function display, by canonical 

representation, 6 65. 
function display, in definition 

mode , 6 4. 
function establishment, 47 48 59. 
function establishment, failure 

of, 60. 
function tables, generated by 

outer product, 29. 
functions, list of, 2 74 79. 
functions, primitive scalar, 18. 
functions, used in sample 

application, display of, 4 6. 
fuzz, see comparison tolerance. 



general logarithm, 18 23. 

general offer, of shared variable, 

54. 
global names, as referents of 

system commands and del, 61. 
global objects, in erase command, 

77. 
global use of names, 60. 
grade, 30 38 39. 
greater than, 12 19. 
greatest common divisor, 62 69. 
grid, of consecutive values, 38. 
group, appending new members, 79. 
GROUP, command, 74 78. 
group, dispersal of, 79. 
group, formation of, 78. 
group, in erase command, 77. 
GRP , command , 74 79. 
GRPS, command, 74 79. 



H 



half duplex, shared variable 

access control, 57. 
halted execution, of defined 

function, 60 66 67. 
header, of a function, 7 59 60. 
hierarchy, absence of, 14. 
HOLD, as part of CONTINUE or HOLD 

commands, 74 82 84. 
host system, 47. 
hyperbolic functions, 18 23. 



identification, of user account, 

16 50 83. 
identity elements, 17 19. 
implication, 21 . 
IMPLICIT ERROR, 11 50. 
IMPROPER LIBRARY REFERENCE, 75 82 

83. 
INCORRECT COMMAND, 73. 
INCORRECT SIGN ON, 75. 
INDEX ERROR, 11 . 
index generator, 30 38. 
index of, 30 38. 

index origin, 15 22 37 50 51 76. 
indexing, of arrays by arrays, 7 

30 37. 
inhibition, of set or use of 

shared variable, 57. 
initial value, of shared variable, 

54. 
inner product, conformability of 

arrays , 28 . 
inner product, operator, 7 25. 
input from terminal, 1 70 71 . 
inserting statement, to function 

definition, 63. 
integer part, 21 . 



Index 



89 



interface quota, 54. 
INTERFACE QUOTA EXHAUSTED , 11. 
interrupt, from terminal, 9. 
INTERRUPT, system response, 11. 
interruption, of character input, 

71. 
interruption, of evaluated input, 

71. 
interruption, of pending set or 

use of a shared variable, 55. 
interruption, of system command, 

73. 
inventory, system for, 2 4 6. 
inverse circular functions, 24. 
inverse permutation, 38. 
invoice, in sample application, 6. 
iota, 12 30 38. 
italic, font used for capital 

letters, 10. 
iterative procedures, use of 

branching in, 61 . 
I-becim, 12. 



K 



key, see password. 

keyboard, typewriter-like, 1 12. 

keying time, 51 . 



labels, in function definition, 

62. 
labels, localization of, 62. 
large data array, facilitated by 

generalized access, 4. 
last axis, 37. 
last elements, selection of, by 

take, 36. 
latent expression, 50 51 76. 
least squares approximation, in 

matrix division, 41 . 
left arrow, 9 12. 
left identity, 17. 
LENGTH ERROR, 11 17. 
less than, 12 18 19. 
letters of the alphabet, used to 

form names , 1 . 
LIB, command, 74. 
library, collection of workspaces, 

15 16 80. 
library, public and private, 16 80 

83. 
library number, 77. 
LIBRARY TABLE FULL, trouble rpeort 

during save, 75 82. 
line counter, 50 51 76. 
line drop, automatic saving of 

continue workspace, 82 83. 
line zero, of function definition, 

62. 
list of customers, stored as 

matrix, 3. 



LOAD, command, 2 15 50 51 73 79 

82. 
load, workspace, and execution of 

latent expression, 51 73 79 82. 
local names, in function header, 

60. 
local use of names, 61. 
local variables, and state 

indicator, 80. 
local variables, in function 

execution, 66. 
localization, of function 

arguments and result, 66. 
localization, of system variables, 

50. 
lock, see password, 
locked function, 65 69. 
locked function, interruption of, 

69. 
LOCKED OUT, 84. 
log, 12 14. 
logarithm, 19 22. 
logarithm, absence of general 

identity element for, 17. 
logical complement, 20. 
logical negation, 20. 



M 



magnitude, 18 20. 

material implication, 21. 

matrix, 14. 

matrix divide, 30 40. 

matrix inverse, 30 40. 

matrix product, generalized as 

inner product, 7 28. 
maximum, 18 19 21. 
membership, 30 39. 
message from system operator, 

received at sign on, 84. 
minimum , 10 18 19 21. 
minus , 18 19. 
mixed functions, 17. 
mixed functions, classification 

of, 29. 
monadic, valence of function, 13, 
monadic and dyadic forms of 

primitive functions, 18. 
multiple specification, 9. 
multiplication, 12 18 19 25. 
multi-dimensional arrays, 14. 



N 



name, expunged from workspace, 48. 
name, standing for variable, 1 9. 
name classification, 48 49. 
name list, 48 49. 
named functions or data, benefits 

of using, 2. 
names, distinguished, 47. 
names , for symbols , 10. 



90 



APL Language 



names, in statements from 

keyboard, 1 . 
names, rules for forming, 16 80. 
nand, 12 18. 

natural logarithm, 18 22 23. 
negative, 18 20. 
negative numbers, sign used for, 

13. 
new-line signal, omitted from bare 

output, 72. 
niladic, valence of function, 13. 
NO SHARES, system response, 11. 
NO SPACE, 82. 
nor, 12 18. 
not, logical, 18 20. 
NOT COPIED, 75 78. 
not equal, 12 18 19. 
NOT FOUND, 75 77. 
not greater than, 12 18 19. 
NOT GROUPED, 75 79. 
not less than, 12 18 19. 
NOT SAVED, 75 81 . 
notebook, similiarity to 

workspace, 2. 
null, 12. 

NUMBER IN USE, 75 84. 
NUMBER LOCKED OUT, 75 84. 
NUMBER NOT IN SYSTEM, 75 84. 
numbers, group of used together, 

1. 
numbers , in statements entered 

from keyboard , 1 . 
numeric, characters, 10. 
numerical functions, 29 40. 
OFF, command, 74. 
OFF HOLD, command, 74. 



offer, shared variable, 50 52 54. 

omega , 12. 

one-origin indexing, 15. 

open shoe, 12. 

operators, which modify primitive 

functions, 7 13 17 25. 
or, logical, 12 18 20. 
order, of elements in reshaping an 

array, 32. 
order of execution, 14. 
orders, customer, in sample 

application, 4 6. 
origin, index, 15 22 37 50 51 76. 
out of, combinations, or binomial 

coefficients, 18 19 24 25. 
outer product, operator, 7 29. 
overbar, for negative numbers, 12 

13. 
overstrike, illegitimate, 11. 
overstriking, to form escape 

character from character input, 

71. 



parentheses, 12. 

parentheses, used to indicate 

order of execution, 14. 
password, for user identification, 

16 73 84. 
password, for workspace, 16 76 77 

80 82. 
password, in system commands, 73 

82. 
PCOPY, command, 74 78. 
pendent execution, 67. 
pendent function, and localization 

of names, 61 . 
pendent functions, and state 

indicator, 67. 
permutation, 38. 
permutation, random, 39. 
pi, 23. 

pi times, 18 23. 
plus, 12 18 19. 

polynomial evaluation, see decode, 
power, 18 19 22 25. 
precedence, absence of, for 

functions, 7 14. 
precision, and comparison 

tolerance, 20. 
precision, of character 

representation , 44. 
primitive scalar functions, 18. 
primitive objects, arrays as, 4 

14. 
primitive functions, 

classification of, 17. 
primitive objects, numbers and 

symbols as, 1 . 
primitive functions, symbols for, 

8 10. 
printer, used in conjunction with 

APL, 1 52. 
printing precision, 50 51 72 76. 
printing width, 51. 
printing width, and bare output, 

72. 
printing width, in function 

definition, 50. 
printing width, in normal output, 

72 76. 
private library, 16. 
processor, communicating with APL 

via shared variables, 52. 
program, sequence of statements, 1 

6 61. 
projection, on space spanned by 

column vectors, obtained from 

matrix division, 41. 
prompt, by use of bare output, 72. 
prompting message, before request 

for input, 6. 
protecting copy, 74 78. 
pseudo-random numbers, 22 39. 
public library, 16 80 81 83. 
punch cards, use in conjunction 

with APL, 52. 



Index 



91 



Pythagorean functions, 18 23, 



Q 



quad , 12. 

quad input, 70 71 . 

quad- prime input, 70. 

query, 12. 

quota, of cpu time per entry, 83. 

quota, of saved workspaces, 80 83. 

quota, of shared variables, 54 83. 

quote, 12. 

quote dot, 12. 

quote marks, around character 

constants, 13. 
quote mark, as member of character 

vector , 13. 
quote quad, 12 70. 



reversing half duplex, shared 

variable access control, 57. 
revision, of entry before release, 

9. 
revision, of function definition, 

59 63 64. 
rho, 12. 

rho, reshape, 32. 
rho, to determine shape of array, 

15. 
right arrow, 12 61. 
right identity, 17. 
roll, 18 22. 
root, square, etc., 22. 
rotate, 30 33. 
rotation, 33. 
row, 27. 



R 



radian measure, in argument to 

sin, cos, tan, 23. 
radix, 42. 

random link, 22 50 51 76. 
random number generator, 22. 
random permutation, 39. 
random selection without 

replacement, 39. 
rank, of an array, 14 32. 
rank, of result produced by 

indexing, 38. 
rank, restrictions on, for 

arguments of mixed functions, 

31 . 
RANK ERROR, 11 . 
rank order, 39. 
rank vector, 32. 
ravel, 30 31. 

real numbers, functions on, 17. 
reciprocal, 18 20. 
recursion, 69. 
reduction, operator, 7 25. 
reduction over empty array, 17^25. 
relations, 18 20. 
remainder, 19. 
replace statement, in function 

definition, 63. 
representation, see encode and 

format . 
RESEND, system response, 11. 
reshape, 30 31 . 
residue, 18 19. 
residue, in definition of encode, 

42. 
response, to statements entered 

from keyboard , 1 . 
result, of defined function, 66. 
retraction, of shared variable 

offer, 57. 
return, to release statement being 

entered, 9. 
reverse, 30 33. 



sales, system for, 2 6. 
SAVE, command, 74 80. 
scalar, as argument of inner 

product, 29. 
scalar, constant, 10. 
scalar, for vector in catenate, 

34. 
scalar functions, concept, 17. 
scalar functions, primitive, list 

of, 18. 
scalar in place of vector, for 

mixed functions, 31. 
scaled form, numbers represented 

by, 10. 
scan, operator, 7 25 26. 
selection, functions for, 29 36. 
selector generator, 38. 
Selectric terminal, 51. 
semantic rules , independent of 

data representation, 7. 
semicolon, 12 37. 
sequence of control, 1 7 61. 
set membership, 39. 
setting shared variable, 52 55. 
shadowing, of global names by 

local names, 61 . 
shape, function, 30 31. 
shape, of array, 14 15 32. 
shape vector, 32. 
shared variable, 50 57. 
shared variable offer, 52 53. 
shared variable, and workspace 

full during save, 80. 
shared variable, inquiries 

regarding, 53 57. 
shared variable, quota, 54. 
shared variable, retraction of, 53 

57. 
shared variable, shared with the 

system environment, 50 52. 
shared variable, to communicate 

with processors outside APL, 7. 
SI, command, 11 74 78'. 



92 APL Language 



SI DAMAGE, 11 68 75 78. 

side effects, absence of, 7. 

sign off, procedure for, 84. 

sign on, procedure for, 84. 

significance, of names, 1. 

signum, 18 20. 

simplex, shared variable access 

control, 57. 
sin, 14 18 23. 
singularity, of matrix to be 

inverted, 40. 
sinh, 18 23. 
SIV, command, 7 4 80. 
size, of array, 3 14. 
slash, 12. 
slash bar, 12. 
slope, 12. 
slope bar, 12. 
space , 12. 

spaces, as separators, 13. 
special characters, 10. 
specification, 9. 
specification, multiple, 9. 
star, 12. 

state indicator, 15 67 74 80. 
state indicator damage, 11 68 75 

78. 
state indicator, clearing, 67 76 

79. 
state indicator, with display of 

local variables, 74 80. 
statement, 1 73. 
statement, entered from keyboard, 

1. 
statement, form of, 9. 
statement types, listed, 7. 
stile, 12. 

stop control, 66 68. 
storage and retrieval , of 

workspaces, 73. 
strong interrupt, 9. 
structure, functions for, 29. 
structure, of arrays, 14. 
subtraction, 13 18. 
surrogate name, for shared 

variable, 52 53. 
suspended execution, 61 67 80. 
suspended function, and 

localization of names, 61 67 

80. 
suspended function, and state 

indicator, 61 67 80. 
suspended function, automatic 

restart by latent expression, 

50. 
symbol table, 76 78. 
SYMBOL TABLE FULL, 11 75. 
SYMBOLS, command, 74 77 79. 
symbols, in statements entered 

from keyboard , 1 . 
symbols, used to represent 

primitive functions, 8 10. 
syntax, 1 7 14 59 60. 
SYNTAX ERROR, 11. 
system commands, 16 73 74. 



SYSTEM ERROR, 11 . 

system functions, 47 48. 

system variables, to communicate 

with APL environment ,71517 

47 50. 



table, as matrix, 14. 
tables, generated by outer 

product, 29. 
table-generating functions, 25. 
tabular displays, use of format to 

generate, 46. 
take, 30 36. 
tan, 18 23. 
tanh, 18 23. 
tapes, communication through 

shared variable, 1 52. 
terminal, common characteristics 

of, 9. 
terminal, typewriter-like, 9. 
terminal, video, 9. 
terminal control characters, 

obtained from atomic vector, 

51. 
terminal type, 51. 
text processing, 70. 
three-dimensional array, example 

of, 3. 
tilde, 12. 
time stamp, 50 51. 
times, 12 18 19 25. 
top , 12. 
top null, 12. 
trace Control, 68. 
transformations, numeric to 

character and vice versa, 29. 
transpose, general, 30 35. 
transpose, ordinary, 30 35. 
trigonometric functions , see 

circular functions, 
trouble reports, 75. 
true, number 1 used to represent, 

20. 
type, data, 16 29 43. 
type element, non-APL, used for 

application, 3.' 



U 



undefined values from certain 

expressions, 17. 
underbar , 12. 
up arrow, 12. 
upstile, 12. 
use of shared variable facility, 

52. 
user identification, 16 50 83. 
user load, 50 51 . 
using shared variable, restriction 

imposed by access control, 55. 



Index 



93 



V 



valence, function, 7 13. 

VALUE ERROR, 1 1 . 

variable, named collection of 

data, 1 . 
variables, identified by name 

class function, 49. 
variables, list of, 2 74 79. 
VARS, command, 2 74 79. 
vector , entry of , 10 13 14. 



W 



weak interrupt, 9. 
width, of character 

representation, 44. 
work area available, 50 51 76. 
workspace , active ,2 15. 
workspace, as unit of storage, 15 

16. 
workspace, prepared, as example, 

2. 
workspace full, 11 57 69 75 78 79 

30. 
workspace name, 73 74 80. 
WS FULL, 11 57 69 75 78 79 80. 
WS LOCKED, 75 77 79 82. 
WS NOT FOUND, 75 77 79 82. 
WSID, command, 73 74 80. 



zero divided by zero, defined, 19, 
zero-origin indexing, 15. 



94 APL Language 



APL Language Reader's 

GC26-3847-0 Comment 

Form 

Your comments about this publication will help us to improve it for you. 
Comment in the space below, giving specific page and paragraph references 
whenever possible. All comments become the property of IBM. 

Please do not use this form to ask technical questions about IBM systems and 
programs or to request copies of publications. Rather, direct such questions or 
requests to your local IBM representative. 

If you would like a reply, please provide your name, job title, and business 
address (including ZIP code). 



Fold on two lines, staple, and mail. No postage necessary if mailed in the U.S.A. (Elsewhere, 
any IBM representative will be happy to forward your comments.) Thank you for your 
cooperation. 



GC26-3847-0 



Fold and Staple 



First Class Permit 

Number 439 

Palo Alto, California 



Business Reply Mail 

No postage necessary if mailed in the U.S.A. 



Postage will be paid by: 



IBM Corporation 

System Development Division 

LDF Publishing- Department J04 

1501 California Avenue 

Palo Alto, California 94304 




> 

-a 



3 
in 

c 



CO 

o 

ro 

N5 



Q. 

5' 

c 

in 
> 



Fold and Staple 



O 

n 

o> 

CO 
03 



mm 



® 



International Business Machines Corporation 

Data Processing Division 

1 133 Westchester Avenue, White Plains, New York 10604 

(U.S.A. only! 



IBM World Trade Corporation 

821 United Nations Plaza, New York, New York 10017 

(International) 



GC26-3847-0 



> 



0) 

3 

c 



c/5 

CO 

o 



3' 
r-t- 

a. 

C 
CO 

> 
o 

NO 

CT> 

CO 
00 

•P» 
-J 



mm 



International Business Machines Corporation 

Date Processing Division 

1133 Westchester Avenue, White Plains, New York 10604 

(U.S.A. only) 

IBM World Trade Corporation 

821 United Nations Plaza, New York, New York 10017 

(International)